Specification Laravel Package

Getting Started

Minimal Steps

1. Understand the Scope: Since this package is archived and no longer maintained, evaluate if its purpose aligns with your needs. It defines error specifications (e.g., for exception-based error handlers) and provides testing tools to validate conformance.

   • Key files:
     • exception-based-error-handler.md (specification)
     • test/exception-based-error-handler (test scripts)

2. First Use Case:

   • If you need to enforce a custom error-handling contract (e.g., ensuring all exceptions extend a base class or implement specific methods), you could:
     • Fork the repo and adapt the test scripts for your Laravel app.
     • Use the specification as a reference to manually validate error handlers (e.g., in PHPUnit tests).

3. Setup:

   • Clone the repo and inspect the test scripts. No Composer installation is needed—this is a specification/documentation package, not a library.
   • Example workflow:

     git clone https://github.com/php-errors/specification.git
     cd specification/test/exception-based-error-handler
     

Implementation Patterns

Usage Patterns

1. Defining Custom Error Specifications:

   • Extend the existing patterns to document your own error-handling rules. For example:

     # Custom Laravel Error Specification
     ## Requirements
     - All exceptions must implement `Throwable` and include a `getErrorCode()` method.
     - Error handlers must log to `storage/logs/errors.log`.
     

   • Store specs in docs/specs/ in your Laravel project.

2. Testing Conformance:

   • Adapt the provided test scripts (e.g., exception-based-error-handler) to validate your Laravel app’s error handlers.
   • Example PHPUnit test snippet (inspired by the package):

     use PHPUnit\Framework\TestCase;
     
     class CustomErrorHandlerTest extends TestCase
     {
         public function testExceptionConformance()
         {
             $exception = new \App\Exceptions\CustomException('Test', 500);
             $this->assertInstanceOf(\Throwable::class, $exception);
             $this->assertEquals(500, $exception->getErrorCode());
         }
     }
     

3. Integration with Laravel:

   • Error Handling: Use the spec to standardize how exceptions are thrown/caught in your app. For example:

     // app/Exceptions/Handler.php
     public function render($request, Throwable $exception)
     {
         if ($exception instanceof \App\Exceptions\CustomException) {
             // Validate against your spec here
             return response()->json(['error' => $exception->getMessage()], 500);
         }
         return parent::render($request, $exception);
     }
     

   • Logging: Ensure all custom exceptions log to a consistent format (per your spec).

4. Documentation-Driven Development:

   • Treat specs as living documentation. Update them when adding new exception types or error-handling logic.
   • Link specs in your project’s README or CONTRIBUTING.md.

Gotchas and Tips

Pitfalls

1. No Active Maintenance:

   • The package is archived and lacks updates. Use it as reference material only—do not rely on it for production-critical validation.
   • Example: The test scripts may not work out-of-the-box with modern PHPUnit versions.

2. Lack of Laravel-Specific Tools:

   • This package does not integrate with Laravel’s built-in error handling (e.g., App\Exceptions\Handler). You’ll need to manually adapt specs/tests.
   • Avoid assuming compatibility with Laravel’s report() or render() methods.

3. Overhead for Small Projects:

   • If your Laravel app has simple error handling, the effort to document/specify errors may not be justified.
   • Consider lighter alternatives like:
     • PHPUnit’s built-in assertions for exceptions.
     • Custom traits for consistent exception behavior.

Debugging Tips

1. Test Script Issues:

   • If adapting the test scripts, expect deprecated syntax (e.g., PHPUnit_Framework_TestCase). Update to modern PHPUnit:

     // Before (deprecated)
     class OldTest extends PHPUnit_Framework_TestCase {}
     
     // After
     class NewTest extends \PHPUnit\Framework\TestCase {}
     

   • Run tests with --verbose to diagnose failures:

     phpunit --verbose test/exception-based-error-handler/ExceptionTest.php
     

2. Spec Ambiguity:

   • The specs are high-level. Clarify edge cases (e.g., "What counts as a valid error code?") before enforcing them.
   • Example: Should getErrorCode() return null for unknown errors? Document this in your spec.

3. Integration with Laravel’s Error Pages:

   • If using Laravel’s debug/error pages, ensure your specs account for:
     • The debug() method in Handler.php.
     • Custom views (e.g., resources/views/errors/500.blade.php).

Extension Points

1. Custom Validation Logic:

   • Extend the test scripts to include Laravel-specific checks. For example:

     // test/CustomLaravelExceptionTest.php
     public function testLaravelExceptionFormat()
     {
         $exception = new \App\Exceptions\CustomException('Oops');
         $this->assertArrayHasKey('message', $exception->toArray());
         $this->assertArrayHasKey('code', $exception->toArray());
     }
     

2. CI/CD Enforcement:

   • Add a PHPUnit test suite to your Laravel project’s CI pipeline to validate error specs on every commit:

     # .github/workflows/tests.yml
     jobs:
       test:
         runs-on: ubuntu-latest
         steps:
           - run: php artisan test --filter=ExceptionConformanceTest
     

3. Static Analysis:

   • Use tools like Psalm or PHPStan to statically verify exception conformance:

     <!-- psalm.xml -->
     <file-list>
         <directory name="app/Exceptions" />
     </file-list>
     <properties>
         <property name="interfaces_extend_classes" value="true" />
     </properties>
     

   • Add a rule to ensure all exceptions implement your spec’s requirements.

4. Documentation Generation:

   • Convert specs to interactive docs using tools like:
     • Markdown + Mermaid.js for flowcharts of error-handling logic.
     • Laravel’s php artisan docs:generate (if using a custom docs system).
   • Example Mermaid diagram for error flow:

     flowchart TD
         A[Exception Thrown] --> B{Custom?}
         B -->|Yes| C[Validate Spec]
         B -->|No| D[Default Handler]
         C --> E[Log & Render]
     

---