Link Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dbstudios/link-bundle
   

   Add to config/bundles.php (Symfony):

   return [
       // ...
       DbStudios\LinkBundle\DbStudiosLinkBundle::class => ['all' => true],
   ];
   

2. Configuration: Publish the default config:

   php bin/console dbstudios:link:install
   

   Edit config/packages/dbstudios_link.yaml to define your link types (e.g., default, internal, external).

3. First Use Case: Generate a link in a Twig template:

   {{ link('default', { path: 'app_homepage' }) }}
   

   Or in PHP:

   $link = $this->get('link_generator')->generate('default', ['path' => 'app_homepage']);
   

Implementation Patterns

Core Workflows

1. Link Generation:

   • Dynamic Links: Use named routes or absolute paths:

     $link = $this->get('link_generator')->generate('internal', ['_route' => 'user_profile', 'id' => $user->id]);
     

   • Query Parameters: Append via options:

     $link = $this->get('link_generator')->generate('external', ['url' => 'https://example.com', 'query' => ['utm_source' => 'newsletter']]);
     

2. Twig Integration:

   • Extend Twig with custom filters:

     {% set link = link('default', { path: 'contact' }) %}
     <a href="{{ link|url }}">{{ link|title }}</a>
     

   • Access metadata:

     {{ link|isAbsolute }}  {# Checks if link is absolute #}
     

3. Service Integration:

   • Inject LinkGenerator into controllers/services:

     public function __construct(private LinkGenerator $linkGenerator) {}
     
     public function show() {
         $link = $this->linkGenerator->generate('internal', ['_route' => 'product_show', 'id' => 1]);
     }
     

4. Route-Based Links:

   • Leverage Symfony’s router for consistency:

     $link = $this->linkGenerator->generate('default', ['_route' => 'app_home']);
     

5. Asset Links:

   • Generate links for assets (CSS/JS) with a dedicated type:

     # config/packages/dbstudios_link.yaml
     types:
         asset:
             base_url: '%kernel.project_dir%/public/build'
     

     $assetLink = $this->linkGenerator->generate('asset', ['path' => 'styles/main.css']);
     

Gotchas and Tips

Common Pitfalls

1. Configuration Overrides:

   • Avoid hardcoding link types in templates. Use config or environment variables for flexibility.
   • Example: Define base_url per environment in dbstudios_link.yaml.

2. Route Resolution:

   • Ensure named routes exist before generating links. Use _route parameter for route-based links:

     $link = $this->linkGenerator->generate('internal', ['_route' => 'nonexistent_route']); // Throws exception
     

   • Debug with:

     php bin/console debug:router
     

3. Caching:

   • Links are cached by default. Clear cache after config changes:

     php bin/console cache:clear
     

4. Twig Auto-escaping:

   • Use |raw filter if escaping breaks HTML attributes:

     <a href="{{ link|url|raw }}">Link</a>
     

5. External Links:

   • Always validate external URLs to prevent SSRF:

     $url = 'https://' . parse_url($externalUrl, PHP_URL_HOST);
     if (!filter_var($url, FILTER_VALIDATE_DOMAIN)) {
         throw new \InvalidArgumentException('Invalid external URL');
     }
     

Debugging Tips

1. Log Generated Links:

   • Enable debug mode in dbstudios_link.yaml:

     debug: true
     

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

2. Validate Config:

   • Use the validate command:

     php bin/console dbstudios:link:validate
     

3. Custom Link Types:

   • Extend the bundle by creating a custom type service:

     # config/services.yaml
     services:
         App\Link\CustomLinkGenerator:
             tags: ['dbstudios.link.type']
     

   • Implement DbStudios\LinkBundle\Generator\LinkGeneratorInterface.

4. Performance:

   • For high-traffic sites, disable caching for dynamic links:

     types:
         dynamic:
             cache: false
     

5. Testing:

   • Mock LinkGenerator in PHPUnit:

     $mockLink = $this->createMock(Link::class);
     $mockLink->method('getUrl')->willReturn('https://example.com');
     $this->linkGenerator->expects($this->once())->method('generate')->willReturn($mockLink);