Php Raml Parser Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require alecsammon/php-raml-parser
   

   (Note: Due to abandonment, prefer raml-org/raml-php-parser for new projects.)

2. Basic Usage Parse a RAML file (e.g., api.raml):

   use AlesSammon\RamlParser\Parser;
   
   $parser = new Parser();
   $api = $parser->parseFile(__DIR__ . '/api.raml');
   

3. First Use Case: Extract API Metadata Access parsed data (e.g., title, versions, resources):

   echo $api->getTitle(); // "My API"
   $resources = $api->getResources();
   

Implementation Patterns

Workflow: RAML-Driven API Documentation

1. Parse & Cache RAML Store parsed RAML in a service container for reuse:

   $this->api = $parser->parseFile($ramlPath);
   $this->api->getResources(); // Reused across controllers
   

2. Generate API Specs Dynamically Use parsed RAML to auto-generate OpenAPI/Swagger:

   $openApi = convertRamlToOpenApi($this->api);
   

3. Validation Layer Validate incoming requests against RAML definitions:

   $resource = $this->api->getResource('/users/{id}');
   if (!$resource->isValidRequest($request)) {
       abort(400, 'Invalid request format');
   }
   

Integration Tips

• Laravel Service Provider Bind the parser to the container:

  $this->app->singleton(Parser::class, function () {
      return new Parser();
  });
  

• Artisan Command Create a command to parse and log RAML schemas:

  $this->call('raml:parse', ['file' => 'api.raml']);
  

Gotchas and Tips

Pitfalls

1. Abandoned Package

   • No updates since 2017; prefer raml-org/raml-php-parser.
   • Use at your own risk for legacy systems.

2. Strict RAML Compliance

   • Parser may fail on non-standard RAML (e.g., custom types).
   • Test with your RAML spec first.

3. Memory Usage

   • Large RAML files (>10MB) may cause timeouts. Stream parsing is not supported.

Debugging

• Enable Verbose Parsing Set debug mode for detailed errors:

  $parser->setDebug(true);
  

• Check RAML Syntax Validate RAML files using RAML Lint before parsing.

Extension Points

1. Custom Type Handlers Override default type handling (e.g., for proprietary formats):

   $parser->addTypeHandler('custom-type', function ($value) {
       return json_decode($value);
   });
   

2. Post-Parse Hooks Modify parsed data via events:

   $parser->on('parse.complete', function ($api) {
       $api->setCustomMetadata(['author' => 'Your Team']);
   });
   

3. Laravel Integration

   • Middleware: Validate API requests against RAML.
   • API Docs: Auto-generate Swagger UI from parsed RAML.