Exceptionchecker Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require c975l/exceptionchecker-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       C975L\ExceptionCheckerBundle\ExceptionCheckerBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console exceptionchecker:install
   

   Update config/packages/exceptionchecker.yaml with your:

   • secret_code (optional, if not logged in)
   • redirect_url (default: /)
   • ignored_urls (wildcards supported, e.g., "/admin/*")

3. First Use Case

   • Trigger a 404 on a broken URL (e.g., https://your-site.com/nonexistent-page).
   • Check your Monolog email for a link to the ExceptionChecker form.
   • Log in (or enter the secret code) and mark the URL as excluded/redirected via the form.

Implementation Patterns

Workflows

1. Catching and Redirecting

   • The bundle listens to kernel.exception and kernel.controller events.
   • For 404s/500s, it checks if the URL matches any ExceptionChecker rules (case-insensitive, wildcards).
   • If matched:
     • Redirects to redirect_url (default: /).
     • Logs the action (via Monolog).
   • For deleted URLs, throws a GoneHttpException (HTTP 410).

2. Admin Management

   • Access the ExceptionChecker dashboard at /_exceptionchecker (configurable).
   • CRUD operations for rules:
     • Create: Auto-detects broken URLs from exceptions.
     • Modify: Adjust wildcards, redirect targets, or status (active/inactive).
     • Duplicate: Clone rules with minor edits.
     • Delete: Marks URLs as "gone" (triggers 410).

3. Integration with Symfony

   • Twig Integration: Use {{ dump(exceptionchecker) }} to debug rules in templates.
   • Event Subscribers: Extend functionality via kernel.exception:

     // src/EventListener/CustomExceptionListener.php
     public function onKernelException(GetResponseForExceptionEvent $event) {
         $exception = $event->getThrowable();
         if ($exception instanceof \Symfony\Component\HttpKernel\Exception\NotFoundHttpException) {
             // Custom logic before ExceptionCheckerBundle processes it
         }
     }
     

   • Monolog Handler: Configure Monolog to log ExceptionChecker actions:

     # config/packages/monolog.yaml
     handlers:
         exceptionchecker:
             type: stream
             path: "%kernel.logs_dir%/exceptionchecker.log"
             level: info
             channels: ["exceptionchecker"]
     

4. Wildcard Rules

   • Define patterns like:

     ignored_urls:
         - "/old-*/"          # Redirects /old-page1/, /old-page2/, etc.
         - "/api/v1/*/delete" # Catches all DELETE endpoints under /api/v1/
     

Gotchas and Tips

Pitfalls

1. Case Sensitivity

   • The bundle normalizes URLs to lowercase for matching, but original case is preserved in logs.
   • Example: /YourFile.html and /yourfile.html are treated as the same rule.

2. Secret Code Security

   • If using secret_code, ensure it’s stored securely (e.g., in parameters.yaml with encryption: true).
   • Avoid hardcoding in version control.

3. Performance with Wildcards

   • Complex wildcards (e.g., "/**/*") may slow down exception handling.
   • Test with php bin/console debug:router to validate URL matching.

4. Monolog Configuration

   • Ensure Monolog is configured to send emails for error level (or higher) to avoid missing broken-link alerts.
   • Example:

     # config/packages/monolog.yaml
     handlers:
         main:
             level: error
             type: fingers_crossed
             action_level: error
             handler: nested
     

5. GoneHttpException (410)

   • URLs marked as "deleted" will not redirect—they throw a 410.
   • Useful for SEO (search engines drop soft 404s but respect 410s).

6. CSRF Protection

   • The admin form includes CSRF tokens by default. If bypassing (e.g., API), manually validate:

     $this->denyAccessUnlessGranted('ROLE_EXCEPTIONCHECKER_EDIT');
     

Debugging

1. Log Exceptions Enable debug mode to see raw exception data:

   php bin/console debug:exception
   

   Filter for C975L\ExceptionCheckerBundle\Exception\GoneHttpException.

2. Check Rule Matches Use the debug toolbar to inspect ExceptionChecker rules:

   // In a controller
   $rules = $this->get('exceptionchecker.rule_manager')->getAllRules();
   dd($rules);
   

3. Clear Cache After Config Changes

   php bin/console cache:clear
   

Extension Points

1. Custom Exception Types Extend the bundle to handle non-Symfony exceptions:

   // src/EventSubscriber/CustomExceptionSubscriber.php
   public function onKernelException(GetResponseForExceptionEvent $event) {
       $exception = $event->getThrowable();
       if ($exception instanceof \Your\Custom\Exception) {
           $ruleManager = $this->container->get('exceptionchecker.rule_manager');
           if ($ruleManager->isUrlIgnored($exception->getUrl())) {
               $event->setResponse(new RedirectResponse('/custom-redirect'));
           }
       }
   }
   

2. Add Fields to Rules Override the form type:

   // src/Form/ExceptionCheckerType.php
   public function buildForm(FormBuilderInterface $builder, array $options) {
       $builder->add('custom_field', TextType::class);
   }
   

3. Hook into Rule Creation Subscribe to the exceptionchecker.rule.created event:

   // src/EventListener/RuleCreatedListener.php
   public function onRuleCreated(RuleEvent $event) {
       $rule = $event->getRule();
       // Add metadata or trigger side effects
   }
   

4. Override Templates Copy the bundle’s templates to templates/bundles/exceptionchecker/ to customize:

   • rule_form.html.twig (admin form)
   • redirect.html.twig (secret code form)