Seo Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require austral/seo-bundle
   

   Ensure Austral\SeoBundle\AustralSeoBundle is registered in config/bundles.php.

2. Configuration: Publish the default config:

   php bin/console austral:seo:install
   

   Update config/packages/austral_seo.yaml (e.g., enable/disable features like url_parameter or redirection).

3. First Use Case:

   • Basic SEO Metadata: Use the SeoMetadata trait in your controller or entity:

     use Austral\SeoBundle\Traits\SeoMetadata;
     
     class PageController
     {
         use SeoMetadata;
     
         public function show(Page $page): Response
         {
             $this->setSeoMetadata($page); // Auto-fills OpenGraph, Twitter, and canonical tags
             return $this->render('page/show.html.twig', ['page' => $page]);
         }
     }
     

   • URL Parameters: Annotate your entity to auto-generate SEO-friendly URLs:

     use Austral\SeoBundle\Annotation\UrlParameterObject;
     
     #[UrlParameterObject]
     class BlogPost
     {
         // ...
     }
     

Implementation Patterns

Core Workflows

1. Entity-Driven SEO:

   • Annotations: Use @UrlParameterObject on entities to auto-generate SEO URLs (e.g., /blog/{slug}).
   • Dynamic Metadata: Override getSeoTitle(), getSeoDescription(), etc., in your entity or DTO:

     class Product
     {
         public function getSeoTitle(): string
         {
             return "Buy {$this->name} - Best Price";
         }
     }
     

2. URL Parameter Management:

   • CRUD via CLI:

     php bin/console austral:seo:url-parameter:list
     php bin/console austral:seo:url-parameter:create BlogPost slug
     

   • Programmatic API:

     $this->get('austral.seo.url_parameter.management')->create(
         'BlogPost',
         'slug',
         'blog/{slug}'
     );
     

3. Redirection Handling:

   • Auto-Redirects: Enable redirection.enabled: true in config. The bundle auto-creates redirects when UrlParameter paths change (e.g., /old-path → /new-path).

4. Multi-Domain Support:

   • Configure domains in austral_seo.yaml:

     domains:
         - 'example.com'
         - 'blog.example.com'
     

   • Use getDomain() in entities to return the correct base URL.

5. Twig Integration:

   • Auto-renders SEO tags in templates:

     {{ seo_metadata(page) }}
     

   • Extend with custom tags:

     {% block seo_custom %}
         <meta property="article:published_time" content="{{ page.publishedAt|date('c') }}">
     {% endblock %}
     

Integration Tips

• Symfony UX: Pair with symfony/ux-turbo for SPA-like SEO (e.g., hydrate metadata via API calls).
• Doctrine Events: Listen for prePersist/preUpdate to update SEO fields:

  $entity->setSeoDescription($this->generateDescription($entity));
  

• API Projects: Use SeoMetadata in API controllers to return SEO headers (e.g., X-Robots-Tag).

Gotchas and Tips

Pitfalls

1. Annotation Cache:

   • After adding @UrlParameterObject, clear the cache:

     php bin/console cache:clear
     

   • Debug missing annotations with:

     php bin/console debug:container austral.seo.url_parameter.listener
     

2. Redirection Conflicts:

   • Disable auto-redirection temporarily during migrations:

     redirection:
         enabled: false
     

   • Manually manage redirects via Austral\SeoBundle\Entity\Redirection.

3. Multi-Domain Pitfalls:

   • Ensure domain field in entities is populated. Use a listener if missing:

     $entity->setDomain(request()->getHost());
     

4. URL Parameter Validation:

   • Validate UrlParameter paths manually if using custom routes:

     $this->get('validator')->validate(
         $urlParameter,
         new Assert\Regex('/^\/[a-z0-9\-]+\/[a-z0-9\-]+$/')
     );
     

Debugging

• Log SEO Metadata:

  $this->get('logger')->debug('SEO Metadata', [
      'title' => $this->getSeoTitle(),
      'description' => $this->getSeoDescription(),
  ]);
  

• Check Generated HTML: Use browser dev tools to verify tags (e.g., <meta property="og:title">).

Extension Points

1. Custom Metadata Providers: Override the SeoMetadataProvider service to add logic:

   austral_seo.seo_metadata_provider: App\Service\CustomSeoProvider
   

   class CustomSeoProvider extends SeoMetadataProvider
   {
       public function getSeoTitle($entity): string
       {
           return "[Custom] {$entity->getName()}";
       }
   }
   

2. Event Listeners: Extend SEO logic via events (e.g., seo.metadata.pre_build):

   $event->setTitle($event->getTitle() . " | Custom Suffix");
   

3. Dynamic URL Parameters: Use the UrlParameterObject interface to add custom logic:

   class CustomUrlParameter implements UrlParameterObject
   {
       public function getUrlParameterPath(): string
       {
           return '/custom/{id}-{slug}';
       }
   }
   

Configuration Quirks

• Deprecated Classes: The bundle includes deprecated classes for migration. Remove them post-migration:

  composer remove austral/entity-seo-bundle
  

• Performance: Disable seo.metadata.auto_generate if manually managing metadata to avoid overhead.

Pro Tips

• Bulk SEO Updates: Use the austral:seo:metadata:update command to regenerate metadata for all entities:

  php bin/console austral:seo:metadata:update Product
  

• Localization: Extend SeoMetadata to support multiple languages:

  public function getSeoTitle(string $locale = 'en'): string
  {
      return $this->translator->trans($this->title, [], $locale);
  }
  

• Testing: Mock the SeoMetadata trait in PHPUnit:

  $this->entity->method('getSeoTitle')->willReturn('Test Title');