Seobundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alpixel/seobundle
   

   Register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3/2):

   Alpixel\Bundle\SEOBundle\SEOBundle::class => ['all' => true],
   

2. Database Migration:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

   (Note: The package expects a seo_metatag table; verify schema compatibility.)

3. First Use Case:

   • Sitemap Generation: Configure routes in config/packages/alpixel_seo.yaml:

     alpixel_seo:
         sitemap:
             enabled: true
             routes: ['app_homepage', 'app_blog_post']
     

   • Meta Tags: Annotate a controller to enable dynamic meta tags:

     use Alpixel\Bundle\SEOBundle\Annotation\MetaTag;
     
     /**
      * @Route("/blog/{slug}", name="app_blog_post")
      * @MetaTag("blog_post", providerClass="App\Entity\Post", title="Blog Post: {post:title}")
      */
     public function showPost(Post $post) { ... }
     

Implementation Patterns

Core Workflows

1. Dynamic Meta Tags:

   • Entity Integration: Implement MetaTagPlaceholderInterface in your entity:

     class Post implements MetaTagPlaceholderInterface {
         public function getPlaceholders(): array {
             return [
                 '[post:title]' => $this->title,
                 '[post:description]' => substr($this->content, 0, 160),
             ];
         }
     }
     

   • Annotation Setup: Use @MetaTag on controllers to link entities to routes:

     @MetaTag("product", providerClass="App\Entity\Product", title="Product: {product:name}")
     

   • Admin Configuration: Run php bin/console alpixel:seo:metatag:dump to sync annotations to the DB. Manage patterns via the SonataAdmin panel (if integrated).

2. Sitemap Generation:

   • Route-Based: Define allowed routes in config (see above).
   • Custom Providers: Extend Alpixel\Bundle\SEOBundle\Sitemap\Provider\RouteProvider to add logic (e.g., exclude draft content).
   • XML Output: Access generated sitemaps at /sitemap.xml (default route).

3. Static Meta Tags:

   • (Limited in this package; use Symfony’s Twig or Meta components for static tags.)

Integration Tips

• Symfony 4+: Use autowiring to inject SEOManager:

  public function __construct(private SEOManager $seoManager) {}
  

• Twig Integration: Pass meta tags to templates:

  {% block meta %}
      <title>{{ app.seo.getTitle() }}</title>
      <meta name="description" content="{{ app.seo.getDescription() }}">
  {% endblock %}
  

• Caching: Enable HTTP caching for sitemaps via .htaccess or symfony/webpack-encore:

  <FilesMatch "\.xml$">
      Header set Cache-Control "public, max-age=3600"
  </FilesMatch>
  

Gotchas and Tips

Pitfalls

1. Database Schema:

   • The package expects a seo_metatag table. If migrations fail, manually create it or adjust the schema.
   • Fix: Run php bin/console alpixel:seo:metatag:dump after schema updates.

2. Annotation Registration:

   • Forgetting to run alpixel:seo:metatag:dump after adding @MetaTag annotations will break meta tag generation.
   • Tip: Add a post-install script in composer.json:

     "scripts": {
         "post-install-cmd": [
             "php bin/console alpixel:seo:metatag:dump"
         ]
     }
     

3. Sitemap Routes:

   • Routes must be canonical (e.g., /blog/post not /blog?post=123). Use requirements in routes.yaml to enforce this.
   • Debugging: Check generated sitemaps at /sitemap.xml or enable debug mode:

     alpixel_seo:
         sitemap:
             debug: true
     

4. Placeholder Conflicts:

   • Duplicate placeholders (e.g., [post:title] in multiple entities) will overwrite values. Use unique prefixes like [blog_post:title].
   • Tip: Validate placeholders in getPlaceholders():

     if (empty($this->title)) {
         throw new \RuntimeException("Title required for SEO placeholders.");
     }
     

Debugging

• Log Meta Tags: Enable debug mode in config/packages/dev/alpixel_seo.yaml:

  alpixel_seo:
      debug: true
  

  Logs will appear in var/log/dev.log.

• Check Annotations:

  php bin/console debug:container alpixel.seo.annotation_reader
  

  Verify annotations are loaded.

Extension Points

1. Custom Providers:

   • Extend Alpixel\Bundle\SEOBundle\Sitemap\Provider\AbstractProvider to add logic (e.g., priority scoring):

     class CustomPriorityProvider extends AbstractProvider {
         public function getPriority(): float {
             return $this->isFeatured() ? 1.0 : 0.5;
         }
     }
     

   • Register in services.yaml:

     services:
         App\Sitemap\CustomPriorityProvider:
             tags: ['alpixel.seo.sitemap.provider']
     

2. Override Templates:

   • Copy templates/SEOBundle/Sitemap/sitemap.xml.twig to templates/SEOBundle/Sitemap/ to customize sitemap structure.

3. Event Listeners:

   • Subscribe to seo.metatag.pre_generate to modify tags dynamically:

     use Alpixel\Bundle\SEOBundle\Event\MetaTagEvent;
     
     public function onMetaTagGenerate(MetaTagEvent $event) {
         $event->setTitle("Promo: " . $event->getTitle());
     }
     

     Register as a service with the kernel.event_listener tag.

Configuration Quirks

• SonataAdmin Dependency: The package assumes SonataAdmin for the SEO panel. If not using Sonata, disable the admin section in config:

  alpixel_seo:
      admin:
          enabled: false
  

• PrestaSitemapBundle: The package depends on presta/sitemap-bundle (v1.5). Conflicts may arise with newer versions. Pin the dependency in composer.json:

  "presta/sitemap-bundle": "1.5.0"