README

This skeleton provides a template for building API-only Laravel applications using Doctrine ORM and the laravel-doctrine-jsonapi package for fully compliant JSON:API implementations.

Key Features:

• Doctrine ORM: Replaces Eloquent as the database layer, leveraging Doctrine's advanced data-mapping capabilities via laravel-doctrine/orm.
• Doctrine Migrations: Database migrations using laravel-doctrine/migrations.
• Doctrine Extensions: Extra features (sluggable, timestamps, soft deletes, etc.) via laravel-doctrine/extensions.
• JSON:API: All APIs conform to the JSON:API specification for standardized, robust, and scalable APIs.
• API-Only: No web routes or traditional Blade views are exposed—this skeleton is focused exclusively on backend API development.
• Automatic API Documentation: Generates OpenAPI specs, Postman collections, and human-friendly docs using Scribe.

About This Skeleton

This project is intended as a starting point for developers who want to:

• Use Laravel as the application framework
• Use Doctrine ORM for data persistence (with full support for migrations and extensions)
• Expose only JSON:API-compliant endpoints (no web UI)

You get a clean Laravel installation, ready for Doctrine and JSON:API integration.

Quick Start

You can start a new project using this skeleton by running:

composer create-project sowl/laravel-doctrine-jsonapi-skeleton jsonapi

Main Packages

• laravel/laravel: Laravel framework
• laravel-doctrine/orm: Doctrine ORM integration for Laravel (docs)
• laravel-doctrine/migrations: Integration with Doctrine2's migrations package for Laravel
• laravel-doctrine/extensions: Doctrine extensions for Laravel (Gedmo, Beberlei, etc.)
• sowl/laravel-doctrine-jsonapi: JSON:API implementation for Laravel + Doctrine
• scribe: API documentation generator

TODO List

This is a high-level roadmap for fully implementing the skeleton:

• Remove default Laravel web routes and Blade views
• Install and configure Doctrine ORM (laravel-doctrine/orm)
  • Publish and customize Doctrine config
  • Configure environment variables for Doctrine
• Install and configure Doctrine Migrations (laravel-doctrine/migrations)
  • Set up migration paths
• Install and configure Doctrine Extensions (laravel-doctrine/extensions)
  • Install Gedmo extensions requirement
  • Enable useful extensions (timestamps, sluggable, soft deletes, etc.)
• Set up basic User entity
  • Set up entity folder structure
  • Setup authentication and all the relevant user traits
  • Add migration of the User entity and rest default entities.
  • Tests for authentication logic
• Install and configure laravel-doctrine-jsonapi (sowl/laravel-doctrine-jsonapi)
  • Publish and customize jsonapi.php config
  • Register resources in config/jsonapi.php
• Create sample Doctrine entity implementing ResourceInterface
• Create a transformer extending AbstractTransformer
• Set up API routes (remove web.php, use api.php only)
• Add example resource controller (using default or custom controller)
• Add policy-based authorization for resources
• Add validation for JSON:API requests
• Implement authentication (e.g., Laravel Passport, Sanctum, or JWT)
• Integrate Scribe for automatic generation of OpenAPI specs and API docs
  • Configure Scribe for API-only docs
  • Ensure docs include OpenAPI spec, Postman collection, and sample responses
  • Add custom docs for example resource
• Configure proper exception handling with showing JSON:API errors.
• Use GUID for the primary key of the entities.
• Implement extensive testing of this skeleton
  • Make sure all features work as expected
  • Add tests for queue-failed jobs
  • Add tests for cache
  • Add tests for authentication
  • Add tests for authorization
  • Add tests for validation
  • Add tests for API endpoints
  • Add tests for API docs
• Implement RBAC (Role-Based Access Control) authorization logic
  • Define roles and permissions (e.g., Admin, User, Guest)
  • Assign roles to users and restrict resource actions accordingly
  • Add policies and middleware for RBAC enforcement
  • Document RBAC usage and configuration
• Add detailed onboarding and contribution guide for new developers
  • Document setup, coding standards, and contribution workflow
  • Provide example PR and review process
  • Add FAQ and troubleshooting section
• Build and document default .windsurfrules for this repository
  • Describe commit, branch, and review policies
  • Add rules for sensitive files, migrations, and API docs
  • Ensure .windsurfrules is kept up to date with project conventions
• Add API rate limiting and throttling
  • Configure Laravel's built-in rate limiting for API endpoints
  • Add custom logic for user/role-based limits if needed
• Set up CI/CD for automated testing and code quality checks
  • Set up GitHub Actions for CI/CD
  • Set up GitHub Actions for code quality checks
• Move the scribe.blade.php to the base library.

References

• Laravel Doctrine ORM Documentation
• Doctrine ORM Documentation
• Doctrine Migrations Documentation
• Doctrine Extensions Documentation
• laravel-doctrine-jsonapi Documentation
• Scribe Documentation
• Scribe GitHub
• JSON:API Specification

License

This project is open-source and available under the MIT license.