Ez Support Tools Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Add the bundle via Composer:

   composer require ezsystems/ez-support-tools
   

   Enable the bundle in config/app.php under providers:

   EzSystems\EzSupportToolsBundle\EzSupportToolsBundle::class,
   

2. First Use Case: System Information Access system details via the CLI command:

   php bin/console ez-support-tools:system-info
   

   This generates a JSON/HTML report of:

   • PHP environment
   • Database connection
   • OS details
   • Composer dependencies
   • Symfony kernel version

3. Where to Look First

   • CLI Commands: vendor/bin/console list ez-support-tools (for available commands).
   • Configuration: config/packages/ez_support_tools.yaml (if present).
   • Templates: templates/ez_support_tools/ (for customizing output).

Implementation Patterns

Common Workflows

1. Debugging Environment Issues

   • Use ez-support-tools:system-info to compare dev/staging/prod environments.
   • Example: Check PHP extensions mismatch between environments:

     php bin/console ez-support-tools:system-info --format=json | jq '.php.extensions'
     

2. Automated Reporting

   • Integrate with CI/CD pipelines to log system info on failures:

     # .github/workflows/test.yml
     jobs:
       test:
         runs-on: ubuntu-latest
         steps:
           - run: php bin/console ez-support-tools:system-info > system_report.json
           - uses: actions/upload-artifact@v3
             with:
               name: system-report
               path: system_report.json
     

3. Customizing Output

   • Override Twig templates (e.g., templates/ez_support_tools/system_info.html.twig).
   • Extend the collector system by implementing EzSystems\EzSupportToolsBundle\Collector\CollectorInterface:

     // src/Collector/CustomCollector.php
     namespace App\Collector;
     
     use EzSystems\EzSupportToolsBundle\Collector\CollectorInterface;
     
     class CustomCollector implements CollectorInterface {
         public function collect(): array {
             return ['custom_key' => 'custom_value'];
         }
     }
     

   • Register the collector in services.yaml:

     services:
         App\Collector\CustomCollector:
             tags: ['ez_support_tools.collector']
     

4. API-Driven Debugging

   • Expose system info via an API endpoint (e.g., using Symfony’s JsonResponse):

     // src/Controller/SystemInfoController.php
     use EzSystems\EzSupportToolsBundle\Collector\CollectorManager;
     
     class SystemInfoController extends AbstractController {
         public function __invoke(CollectorManager $collectorManager): JsonResponse {
             return new JsonResponse($collectorManager->collect());
         }
     }
     

   • Route it in config/routes.yaml:

     ez_support_tools.api:
         path: /_support/system-info
         controller: App\Controller\SystemInfoController
     

Gotchas and Tips

Pitfalls

1. Sensitive Data Exposure

   • Risk: System reports may include sensitive data (e.g., database credentials, API keys).
   • Fix: Use --exclude-sensitive flag or override the SensitiveDataCollector to redact fields:

     // src/Collector/SensitiveDataCollector.php
     namespace App\Collector;
     
     use EzSystems\EzSupportToolsBundle\Collector\SensitiveDataCollector as BaseCollector;
     
     class SensitiveDataCollector extends BaseCollector {
         protected function getSensitiveKeys(): array {
             return array_merge(parent::getSensitiveKeys(), ['db_password']);
         }
     }
     

2. Performance Overhead

   • Risk: Collecting system info can be resource-intensive in production.
   • Fix: Disable collectors in production or use --collectors to specify only critical ones:

     php bin/console ez-support-tools:system-info --collectors=php,os
     

3. Template Caching

   • Issue: Twig templates may not update if the cache is enabled.
   • Fix: Clear the cache after modifying templates:

     php bin/console cache:clear
     

4. Dependency Conflicts

   • Risk: The bundle may conflict with other ezsystems/* packages if versions are mismatched.
   • Fix: Pin versions in composer.json:

     "require": {
         "ezsystems/ez-support-tools": "^1.0",
         "ezsystems/platform": "^1.0"
     }
     

Debugging Tips

1. Log Collectors Enable debug mode to log collector output:

   php bin/console debug:config ez_support_tools | grep collectors
   

2. Validate JSON Output Use jq to validate JSON structure:

   php bin/console ez-support-tools:system-info --format=json | jq .
   

3. Check for Deprecated Methods Run static analysis tools like PHPStan to catch deprecated API usage:

   vendor/bin/phpstan analyse src --level=5
   

Extension Points

1. Custom Collectors

   • Implement CollectorInterface and tag as ez_support_tools.collector (as shown above).
   • Example: Add a RedisCollector for Redis server details.

2. Hook into Commands Extend existing commands by overriding them (e.g., SystemInfoCommand):

   // src/Command/CustomSystemInfoCommand.php
   namespace App\Command;
   
   use EzSystems\EzSupportToolsBundle\Command\SystemInfoCommand;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class CustomSystemInfoCommand extends SystemInfoCommand {
       protected function execute(InputInterface $input, OutputInterface $output): int {
           // Custom logic before/after parent execution
           return parent::execute($input, $output);
       }
   }
   

   Register the command in services.yaml:

   services:
       App\Command\CustomSystemInfoCommand:
           tags: ['console.command']
           arguments:
               $collectorManager: '@ez_support_tools.collector_manager'
           decorates: 'ez_support_tools.system_info'
   

3. Event Listeners Listen for ez_support_tools.collect events to modify data dynamically:

   // src/EventListener/CustomCollectorListener.php
   namespace App\EventListener;
   
   use EzSystems\EzSupportToolsBundle\Event\CollectEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class CustomCollectorListener implements EventSubscriberInterface {
       public static function getSubscribedEvents(): array {
           return [
               CollectEvent::NAME => 'onCollect',
           ];
       }
   
       public function onCollect(CollectEvent $event): void {
           $event->addData(['custom_metric' => microtime(true)]);
       }
   }