Schema Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package to your Laravel project via Composer:

   composer require phpcq/schema
   

   No additional configuration is required if you're only consuming the schemas.

2. Locate Schema Files The package provides two primary schema files:

   • repository-schema.json (for defining repository structures)
   • report-schema.json (for validating phpcq report outputs) Access them via:

   use Phpcq\Schema\Schemas;
   $repositorySchema = Schemas::repository();
   $reportSchema     = Schemas::report();
   

3. First Use Case: Validate a Repository Structure

   use Phpcq\Schema\Validator;
   $validator = new Validator(Schemas::repository());
   $isValid = $validator->validate($yourRepositoryStructureArray);
   

Implementation Patterns

Schema-Driven Development

Repository Schema Integration Use the schema to enforce consistent repository structures across tools/plugins:

// Example: Validate a new plugin directory structure
$pluginStructure = [
    'name' => 'my-plugin',
    'tools' => ['phpcs', 'phpmd'],
    'config' => ['ruleset' => 'path/to/ruleset.xml']
];
$validator = new Validator(Schemas::repository());
$validator->validate($pluginStructure);

Report Schema for Consistency Validate phpcq report outputs before processing:

// In a service handling reports
public function processReport(array $reportData): void
{
    $validator = new Validator(Schemas::report());
    if (!$validator->validate($reportData)) {
        throw new \InvalidArgumentException('Report data does not match schema');
    }
    // Proceed with processing
}

Workflow Integration

1. Plugin Development

• Use the repository schema to scaffold new plugins:

  $defaultStructure = json_decode(file_get_contents(__DIR__.'/schemas/repository-schema.json'), true);
  $newPlugin = array_merge($defaultStructure, ['name' => 'my-new-plugin']);
  

2. CI/CD Validation Add schema validation to your CI pipeline:

# .github/workflows/validate-repo.yml
- name: Validate Repository Structure
  run: |
    php artisan phpcq:validate-repo --schema=vendor/phpcq/schema/repository-schema.json

3. Dynamic Schema Loading Extend the package to load schemas from custom locations:

use Phpcq\Schema\SchemaLoader;
$loader = new SchemaLoader();
$customSchema = $loader->loadFromPath('/custom/path/to/schema.json');

Gotchas and Tips

Pitfalls

1. Schema Versioning

   • The package lacks versioned schemas. If consuming in production, pin the package version:

     composer require phpcq/schema:1.0.0
     

   • Monitor for updates that may break backward compatibility.

2. Strict Validation

   • The validator throws exceptions on failure by default. Use ->validateWithErrors() for custom handling:

     $errors = $validator->validateWithErrors($data);
     if ($errors) {
         // Handle errors gracefully
     }
     

3. Nested Object Validation

   • Deeply nested structures may require recursive validation. Use ->validateRecursive() if available (check package docs).

Debugging Tips

• Schema Inspection Dump the schema structure for debugging:

  dd(json_encode(Schemas::repository(), JSON_PRETTY_PRINT));
  

• Partial Validation Validate specific paths in large structures:

  $validator->validatePath($data, 'tools.*.config');
  

Extension Points

1. Custom Validators Extend the base validator for domain-specific rules:

   use Phpcq\Schema\Validator as BaseValidator;
   
   class PluginValidator extends BaseValidator {
       public function validatePluginName(string $name): bool {
           return preg_match('/^[a-z0-9-]+$/', $name);
       }
   }
   

2. Schema Merging Combine multiple schemas for complex validation:

   $mergedSchema = array_merge(
       Schemas::repository(),
       ['additionalProperties' => false] // Example: Add global rules
   );
   

3. Performance

   • Cache validated schemas in production:

     $validator = new Validator(Schemas::repository());
     $validator->setCache($cache); // Inject a cache instance