Datasource Laravel Package

Getting Started

Minimal Setup in Laravel

1. Installation Since cakephp/datasource is not Laravel-native, install via Composer (if needed for legacy CakePHP patterns):

   composer require cakephp/datasource
   

   (Note: Laravel’s Eloquent already handles most of this—this package is niche for custom data sources.)

2. First Use Case: Custom Data Source Use the Cake\Datasource\ConnectionManager trait to manage non-DB connections (e.g., APIs, NoSQL):

   use Cake\Datasource\ConnectionManager;
   
   class ApiDataSource {
       use ConnectionManager;
   
       public function __construct() {
           $this->loadConnection('api', [
               'className' => 'Cake\Datasource\Connection\ClientConnection',
               'driver'    => 'Cake\Datasource\Connection\ClientConnection',
               'config'    => ['baseUrl' => 'https://api.example.com']
           ]);
       }
   }
   

3. Key Classes to Explore

   • ConnectionManager: Manages connections (like Laravel’s DB facade).
   • Query: Builds queries for custom sources (similar to Eloquent’s Builder).
   • Entity: Maps data to objects (like Eloquent models).

Implementation Patterns

1. Connection Management

• Laravel Integration: Replace Laravel’s DB facade for non-DB sources:

  // In a service provider
  $this->app->singleton('api', function ($app) {
      return new ApiDataSource();
  });
  

• Dynamic Connections: Use ConnectionManager::config() to switch sources at runtime.

2. Query Building

• Fluent Interface: Chain methods like Eloquent:

  $query = $this->ApiDataSource->newQuery()
      ->select(['id', 'name'])
      ->where(['active' => true]);
  

• Custom Drivers: Extend Cake\Datasource\Connection\ClientConnection for APIs/NoSQL.

3. Entity Mapping

• Auto-Mapping: Convert API responses to objects:

  use Cake\Datasource\Entity\Entity;
  
  $user = new Entity(['id' => 1, 'name' => 'John'], ['alias' => 'User']);
  

• Validation: Use Cake\Validation\Validator for data rules (like Laravel’s FormRequest).

4. Hybrid Workflows

• Mix Eloquent + CakePHP: Use Cake’s Query for complex joins, then hydrate with Eloquent:

  $results = $this->ApiDataSource->execute($query);
  return User::hydrate($results->toArray());
  

Gotchas and Tips

Pitfalls

1. Laravel vs. CakePHP Quirks

   • Cake’s Entity lacks Laravel’s mass assignment protection. Use protected $_accessible or Cake\ORM\Table::validate().
   • Query builder syntax differs (e.g., ->find('all') vs. Eloquent’s ->get()).

2. Connection Caching

   • Connections are singleton by default. Override ConnectionManager::getConnection() to avoid leaks.

3. No Built-in Migrations

   • Use Laravel’s migrations for DB, but Cake’s Schema for custom sources requires manual setup.

Debugging Tips

• Enable Logging:

  ConnectionManager::config('Log', ['enabled' => true, 'queries' => true]);
  

• Query Dumping:

  $query->sql(); // Returns raw SQL (or API request string for custom drivers).
  

Extension Points

1. Custom Drivers Extend Cake\Datasource\Connection\ConnectionInterface for new data sources (e.g., GraphQL):

   class GraphQLConnection implements ConnectionInterface {
       public function execute($sql, $params = []) {
           // Custom logic
       }
   }
   

2. Event Listeners Hook into ConnectionManager::config() or Query::beforeExecute() for middleware.

3. Laravel Service Providers Bind Cake’s TableRegistry to Laravel’s container:

   $this->app->bind('Cake\ORM\TableRegistry', function ($app) {
       return new TableRegistry($app['db']);
   });
   

Performance Notes

• Batch Loading: Use ->batch([1, 2, 3]) for API calls (like Eloquent’s ->findMany()).
• Avoid N+1: Cake’s contain() works similarly to Eloquent’s with().