Wellknown Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require baikal/wellknown-bundle
   

   Enable the bundle in config/bundles.php (Symfony):

   return [
       // ...
       Baikal\WellknownBundle\BaikalWellknownBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config (if needed) and adjust in config/packages/baikal_wellknown.yaml:

   php bin/console baikal:wellknown:install
   

   Verify the .well-known directory exists at your web root (e.g., /var/www/html/.well-known).

3. First Use Case Generate a basic change-password endpoint (common for OAuth/CalDAV):

   php bin/console baikal:wellknown:generate change-password
   

   This creates a file like .well-known/change-password with a URL or token.

Implementation Patterns

Common Workflows

1. Dynamic Endpoint Generation Use the CLI to generate endpoints on demand (e.g., for OAuth flows):

   php bin/console baikal:wellknown:generate oauth-authorization
   

   • Store generated files in a version-controlled directory (e.g., .well-known/) or a database-backed system.

2. Integration with Authentication Combine with Symfony’s security system to validate requests to .well-known endpoints:

   # config/routes.yaml
   baikal_wellknown:
       resource: "@BaikalWellknownBundle/Resources/config/routing.yaml"
       prefix: /.well-known
       defaults: { _controller: Baikal\WellknownBundle\Controller\WellknownController::index }
   

   • Add middleware to log or sanitize incoming requests.

3. Custom Templates Override default templates by copying them from: vendor/baikal/wellknown-bundle/Resources/views/ to: templates/baikal_wellknown/ Modify as needed (e.g., add CSRF tokens or custom metadata).

4. API-Driven Generation For dynamic environments, expose an API endpoint to trigger generation:

   // src/Controller/WellknownApiController.php
   use Symfony\Component\HttpFoundation\Response;
   use Symfony\Component\Routing\Annotation\Route;
   
   class WellknownApiController {
       #[Route('/api/wellknown/generate', methods: ['POST'])]
       public function generate(string $endpoint): Response {
           $generator = $this->get('baikal_wellknown.generator');
           $generator->generate($endpoint);
           return new Response('Generated');
       }
   }
   

Gotchas and Tips

Pitfalls

1. Web Root Permissions Ensure the .well-known directory is writable by the web server:

   chmod -R 755 /var/www/html/.well-known
   

   • Debugging: Check storage/logs/debug.log for permission errors.

2. Caching Headers Avoid caching .well-known files aggressively. Add headers in your web server config:

   location /.well-known/ {
       expires -1;
       add_header Cache-Control "no-cache, no-store, must-revalidate";
   }
   

3. Security Risks

   • Exposed Tokens: Never hardcode secrets in generated files. Use environment variables or a secrets manager.
   • Validation: Always validate requests to .well-known endpoints (e.g., check HTTP_REFERER or use Symfony’s voter system).

4. Symfony Event Dispatching The bundle doesn’t natively dispatch events for generation. Extend it by creating a custom event listener:

   // src/EventListener/WellknownGenerateListener.php
   use Baikal\WellknownBundle\Event\WellknownGenerateEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class WellknownGenerateListener implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               WellknownGenerateEvent::NAME => 'onGenerate',
           ];
       }
   
       public function onGenerate(WellknownGenerateEvent $event) {
           // Log or modify the generated content
           $this->logger->info('Generated endpoint: ' . $event->getEndpoint());
       }
   }
   

Tips

1. Environment-Specific Config Use Symfony’s parameter bags to switch between dev/prod configurations:

   # config/packages/baikal_wellknown.yaml
   baikal_wellknown:
       endpoints:
           change-password: "%env(APP_CHANGE_PASSWORD_URL)%"
   

2. Testing Mock the generator in PHPUnit:

   $generator = $this->createMock(\Baikal\WellknownBundle\Generator::class);
   $generator->expects($this->once())
       ->method('generate')
       ->with('test-endpoint');
   $this->container->set('baikal_wellknown.generator', $generator);
   

3. Extending Endpoints Add custom logic to the WellknownGenerator service by overriding it:

   # config/services.yaml
   services:
       Baikal\WellknownBundle\Generator:
           class: App\Service\CustomWellknownGenerator
           arguments:
               $defaultGenerator: '@baikal_wellknown.generator.default'
   

   // src/Service/CustomWellknownGenerator.php
   use Baikal\WellknownBundle\Generator\DefaultGenerator;
   
   class CustomWellknownGenerator extends DefaultGenerator {
       public function generate(string $endpoint) {
           // Pre-process or post-process the content
           parent::generate($endpoint);
       }
   }
   

4. Documentation Gaps The bundle lacks detailed docs. Reverse-engineer by inspecting:

   • src/Generator/DefaultGenerator.php (core logic).
   • Resources/config/routing.yaml (endpoint routes).
   • Resources/views/ (templates).