Getting Started

Minimal Setup for Laravel Integration

Installation
```
composer require doctrine/odm-orientdb
```
Since the package is archived, ensure compatibility with your PHP version (8.0+ recommended).

Basic Configuration Create a config/orientdb.php file:

return [
    'connection' => [
        'host' => env('ORIENTDB_HOST', 'localhost'),
        'port' => env('ORIENTDB_PORT', 2424),
        'username' => env('ORIENTDB_USERNAME', 'root'),
        'password' => env('ORIENTDB_PASSWORD', 'root'),
        'database' => env('ORIENTDB_DATABASE', 'test'),
    ],
    'driver_options' => [
        'connect_timeout' => 2,
    ],
];

First Use Case: Connecting to OrientDB Register the Doctrine service provider in config/app.php:

'providers' => [
    // ...
    Doctrine\ODM\OrientDB\OrientDBServiceProvider::class,
],

Publish the config:

php artisan vendor:publish --provider="Doctrine\ODM\OrientDB\OrientDBServiceProvider"

Define a Model

namespace App\Models;

use Doctrine\ODM\OrientDB\Mapping\Annotation as ODM;

/** @ODM\Document */
class User
{
    /** @ODM\Id */
    private $id;

    /** @ODM\Field(type="string") */
    private $name;

    // Getters and setters...
}

Basic CRUD Operations

use Doctrine\ODM\OrientDB\DocumentManager;

$dm = app(DocumentManager::class);
$user = new User();
$user->setName('John Doe');
$dm->persist($user);
$dm->flush();

Implementation Patterns

Workflow: Repository Pattern Integration

Create a Custom Repository

namespace App\Repositories;

use Doctrine\ODM\OrientDB\DocumentRepository;
use App\Models\User;

class UserRepository extends DocumentRepository
{
    public function findByName(string $name): ?User
    {
        return $this->findOneBy(['name' => $name]);
    }
}

Bind the Repository in Laravel

// In a service provider
$this->app->bind(
    UserRepository::class,
    function ($app) {
        return $app->make(DocumentManager::class)
            ->getRepository(User::class);
    }
);

Usage in Controllers

public function show(UserRepository $userRepository)
{
    $user = $userRepository->findByName('John Doe');
    return response()->json($user);
}

Integration Tips

Leverage Laravel’s Eloquent-like Facades Create a facade for DocumentManager:

// app/Facades/OrientDB.php
namespace App\Facades;

use Illuminate\Support\Facades\Facade;

class OrientDB extends Facade
{
    protected static function getFacadeAccessor()
    {
        return 'orientdb.document_manager';
    }
}

$this->app->singleton('orientdb.document_manager', function ($app) {
    return $app->make(DocumentManager::class);
});

Event Listeners for Document Lifecycle

// Listen to pre-persist events
$dm->getEventManager()->addEventListener(
    array('prePersist'),
    function ($event) {
        $document = $event->getDocument();
        $document->setCreatedAt(new \DateTime());
    }
);

Query Builder for Complex Queries

$query = $dm->createQueryBuilder('User')
    ->field('name')->equals('John Doe')
    ->field('age')->greaterThan(25)
    ->getQuery();
$users = $query->getResult();

Transactions

$dm->beginTransaction();
try {
    $dm->persist($user1);
    $dm->persist($user2);
    $dm->flush();
    $dm->commit();
} catch (\Exception $e) {
    $dm->rollback();
    throw $e;
}

Gotchas and Tips

Pitfalls

Archived Package Risks
- The package is archived, meaning no active maintenance. Test thoroughly in a staging environment.
- Consider forking and maintaining it if critical for your project.

Schema Migrations

OrientDB lacks traditional migrations. Use the console to create/update schemas:
```
php artisan orientdb:schema:update --force
```

Manually create indexes for performance:

$dm->getConnection()->createIndex(
    'UserNameIndex',
    'User',
    'name',
    'UNIQUE'
);

Caching Queries
- OrientDB’s query cache is not managed by Doctrine by default. Configure it in orientdb.php:
```
'query_cache' => [
    'enabled' => true,
    'ttl' => 3600,
],
```

Embedded Documents

Use @ODM\EmbeddedDocument for nested objects, but be mindful of serialization limits:

/** @ODM\EmbeddedDocument */
class Address
{
    /** @ODM\Field(type="string") */
    private $street;
    // ...
}

Connection Pooling
- OrientDB’s PHP driver does not support connection pooling out of the box. Use a connection wrapper or configure the driver manually:
```
$config = $dm->getConfiguration();
$config->setDriverConfig([
    'connect_timeout' => 2,
    'reconnect' => true,
]);
```

Debugging Tips

Enable SQL Logging

$config = $dm->getConfiguration();
$config->setSQLLogger(new \Doctrine\ODM\OrientDB\Logging\EchoSQLLogger());

Check OrientDB Logs
- OrientDB logs are stored in config/log/orientdb.log (default). Enable debug mode in orientdb.php:
```
'logging' => [
    'level' => \Monolog\Logger::DEBUG,
],
```
Common Errors
- "Class not found": Ensure annotations are loaded via Doctrine\Common\Annotations\AnnotationRegistry.
- Connection issues: Verify credentials and network access (OrientDB uses port 2424 by default).
- Schema errors: Use the OrientDB Studio GUI to validate your schema manually.

Extension Points

Custom Hydrators Override how documents are hydrated from the database:

$dm->getHydrator()->registerHydrator(
    'App\Models\User',
    new \Doctrine\ODM\OrientDB\Hydrator\CustomHydrator()
);

Event Subscribers Extend functionality via event listeners (e.g., soft deletes):

$dm->getEventManager()->addEventSubscriber(
    new class implements \Doctrine\ODM\OrientDB\Event\LifecycleEventSubscriber {
        public function preRemove(\Doctrine\ODM\OrientDB\Event\LifecycleEventArgs $args)
        {
            $args->getDocument()->setDeleted(true);
            $args->getDocument()->setDeletedAt(new \DateTime());
        }
    }
);

Custom Types Register custom field types (e.g., for JSON):

$config = $dm->getConfiguration();
$config->addCustomType('json', 'App\Doctrine\Types\JsonType');

Bulk Operations Use OrientDB’s native bulk APIs for performance:

$dm->getConnection()->executeBulkQuery(
    'UPDATE User SET age = age + 1 WHERE age > 25'
);

Orientdb Odm Laravel Package