Parseando URLs do YouTube em PHP: Extraindo IDs de Vídeo de Qualquer Formato

• Introdução
• Pré-requisitos
• Entendendo os Formatos de URL do YouTube
• Construindo o Parser de URL
  • Como os Padrões Funcionam
• Adicionando Métodos Auxiliares
• Testando a Implementação
• Uso Prático: Incorporando Vídeos
• Casos Especiais a Considerar
• Conclusão

Introdução

Ao construir aplicações que se integram com o YouTube, você inevitavelmente encontrará o desafio de lidar com vários formatos de URL. Usuários podem colar uma URL padrão de watch, um link encurtado youtu.be, uma URL de embed, ou até mesmo um link de Shorts. Sua aplicação precisa lidar com todos esses formatos de forma elegante.

Este guia demonstra como construir uma classe UrlUtil que parseia qualquer formato de URL do YouTube e retorna uma URL de embed padronizada, pronta para uso em iframes ou players de vídeo.

Pré-requisitos

• PHP 8.0 ou superior
• Conhecimento básico de expressões regulares
• Familiaridade com a função preg_match do PHP

Entendendo os Formatos de URL do YouTube

O YouTube usa vários formatos de URL, todos apontando para o mesmo vídeo mas estruturados de forma diferente:

Formato	URL de Exemplo	Caso de Uso
Watch padrão	youtube.com/watch?v=dQw4w9WgXcQ	Site principal
URL curta	youtu.be/dQw4w9WgXcQ	Botões de compartilhar
URL de embed	youtube.com/embed/dQw4w9WgXcQ	Incorporação em iframe
Shorts	youtube.com/shorts/dQw4w9WgXcQ	Shorts mobile-first

Todos esses formatos compartilham um elemento em comum: o ID de vídeo de 11 caracteres (dQw4w9WgXcQ nestes exemplos).

Estrutura do ID de Vídeo

Os IDs de vídeo do YouTube sempre têm exatamente 11 caracteres, consistindo em letras (a-z, A-Z), números (0-9), underscores (_) e hífens (-).

Construindo o Parser de URL

Vamos criar uma classe utilitária que lida com todos esses formatos:

<?php

namespace App\Utils;

class UrlUtil
{
    /**
     * Parseia URL do YouTube e converte para formato embed
     * Suporta: youtube.com/watch?v=ID, youtu.be/ID,
     *          youtube.com/embed/ID, youtube.com/shorts/ID
     *
     * @return string|null URL de embed ou null se inválida
     */
    public static function parseYouTubeUrl(string $url): ?string
    {
        if (empty($url)) {
            return null;
        }

        // Define padrões para cada formato de URL
        $patterns = [
            // youtube.com/watch?v=VIDEO_ID ou com parâmetros adicionais
            '/(?:youtube\.com\/watch\?.*v=)([a-zA-Z0-9_-]{11})/',
            // youtu.be/VIDEO_ID
            '/(?:youtu\.be\/)([a-zA-Z0-9_-]{11})/',
            // youtube.com/embed/VIDEO_ID
            '/(?:youtube\.com\/embed\/)([a-zA-Z0-9_-]{11})/',
            // youtube.com/shorts/VIDEO_ID
            '/(?:youtube\.com\/shorts\/)([a-zA-Z0-9_-]{11})/',
        ];

        foreach ($patterns as $pattern) {
            if (preg_match($pattern, $url, $matches)) {
                return 'https://www.youtube.com/embed/' . $matches[1];
            }
        }

        return null;
    }
}

Como os Padrões Funcionam

Cada padrão regex mira um formato específico de URL:

Padrão da URL Watch Padrão:

/(?:youtube\.com\/watch\?.*v=)([a-zA-Z0-9_-]{11})/

• (?:youtube\.com\/watch\?.*v=) - Grupo não-capturador correspondendo ao domínio e caminho
• .*v= - Permite parâmetros de query adicionais antes do parâmetro v
• ([a-zA-Z0-9_-]{11}) - Captura exatamente 11 caracteres válidos

Padrão da URL Curta:

/(?:youtu\.be\/)([a-zA-Z0-9_-]{11})/

• Padrão simples para o domínio encurtado youtu.be
• O ID do vídeo aparece diretamente após a barra

Ordem dos Parâmetros de Query

O padrão da URL watch usa .*v= para lidar com casos onde v não é o primeiro parâmetro, como youtube.com/watch?list=PLxxx&v=VIDEO_ID.

Adicionando Métodos Auxiliares

Você pode querer métodos utilitários adicionais para trabalhar com URLs do YouTube:

/**
 * Verifica se uma URL é uma URL válida do YouTube
 */
public static function isYouTubeUrl(string $url): bool
{
    return self::parseYouTubeUrl($url) !== null;
}

/**
 * Extrai apenas o ID do vídeo sem converter para URL de embed
 */
public static function getYouTubeVideoId(string $url): ?string
{
    $embedUrl = self::parseYouTubeUrl($url);

    if ($embedUrl === null) {
        return null;
    }

    // Extrai o ID da URL de embed
    return substr($embedUrl, -11);
}

Testando a Implementação

Veja como verificar se seu parser lida com todos os formatos corretamente:

// Casos de teste
$urls = [
    'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
    'https://youtube.com/watch?v=dQw4w9WgXcQ&t=30',
    'https://youtu.be/dQw4w9WgXcQ',
    'https://www.youtube.com/embed/dQw4w9WgXcQ',
    'https://youtube.com/shorts/dQw4w9WgXcQ',
    'https://youtube.com/watch?list=PLxxx&v=dQw4w9WgXcQ',
    'url-invalida',
    '',
];

foreach ($urls as $url) {
    $result = UrlUtil::parseYouTubeUrl($url);
    echo $url . ' => ' . ($result ?? 'null') . "\n";
}

Saída esperada:

https://www.youtube.com/watch?v=dQw4w9WgXcQ => https://www.youtube.com/embed/dQw4w9WgXcQ
https://youtube.com/watch?v=dQw4w9WgXcQ&t=30 => https://www.youtube.com/embed/dQw4w9WgXcQ
https://youtu.be/dQw4w9WgXcQ => https://www.youtube.com/embed/dQw4w9WgXcQ
https://www.youtube.com/embed/dQw4w9WgXcQ => https://www.youtube.com/embed/dQw4w9WgXcQ
https://youtube.com/shorts/dQw4w9WgXcQ => https://www.youtube.com/embed/dQw4w9WgXcQ
https://youtube.com/watch?list=PLxxx&v=dQw4w9WgXcQ => https://www.youtube.com/embed/dQw4w9WgXcQ
url-invalida => null
 => null

Uso Prático: Incorporando Vídeos

Uma vez que você tem a URL de embed, pode usá-la no seu HTML:

$userUrl = $_POST['youtube_url'] ?? '';
$embedUrl = UrlUtil::parseYouTubeUrl($userUrl);

if ($embedUrl) {
    echo '<iframe
        width="560"
        height="315"
        src="' . htmlspecialchars($embedUrl) . '"
        frameborder="0"
        allowfullscreen>
    </iframe>';
} else {
    echo '<p>URL do YouTube inválida fornecida.</p>';
}

Nota de Segurança

Sempre use htmlspecialchars() ao exibir URLs em HTML para prevenir ataques XSS. Mesmo que a URL seja validada, defesa em profundidade é essencial.

Casos Especiais a Considerar

Ao trabalhar com URLs do YouTube em produção, tenha estes cenários em mente:

1. Variações de protocolo: URLs podem começar com http://, https://, ou sem protocolo
2. URLs mobile: Alguns apps mobile geram URLs m.youtube.com
3. Parâmetros de timestamp: Usuários podem incluir &t=123 para tempos de início
4. Vídeos privados/não listados: A URL é válida mas o vídeo pode não estar acessível

Para uma solução mais abrangente, você pode estender os padrões:

// Padrão estendido suportando m.youtube.com e URLs sem protocolo
'/(?:(?:https?:)?\/\/)?(?:www\.|m\.)?youtube\.com\/watch\?.*v=([a-zA-Z0-9_-]{11})/'

Conclusão

Parsear URLs do YouTube é um requisito comum ao construir aplicações que lidam com conteúdo de vídeo enviado por usuários. Ao usar uma abordagem baseada em padrões, você pode extrair de forma confiável IDs de vídeo de qualquer formato de URL e convertê-los para um formato de embed padronizado.

Pontos principais:

• IDs de vídeo do YouTube sempre têm 11 caracteres
• Existem múltiplos formatos de URL, cada um requerendo seu próprio padrão regex
• Retorne null para URLs inválidas para permitir tratamento de erros elegante
• Sempre sanitize a saída ao incorporar em HTML

Este utilitário pode ser estendido para suportar plataformas de vídeo adicionais como Vimeo ou Dailymotion adicionando novos padrões e lidando com suas estruturas de URL específicas.