Common Laravel Package

Getting Started

Know what you're installing first. orkestra/common is not a Laravel package — there is no service provider, no facade, no config/*.php to publish. It is a framework-agnostic PHP library of Doctrine 2 helpers, last tagged in September 2014, with zero dependents on Packagist. Treat the install as "vendoring a small utility library," not "adding a dependency."

Minimal steps:

composer require orkestra/common

Then inspect what you actually got before writing a line of code:

1. vendor/orkestra/common/composer.json — read require (PHP constraint and Doctrine version range) and autoload. Packages of this vintage frequently use PSR-0, not PSR-4; this affects whether you can drop your own classes into its namespace.
2. vendor/orkestra/common/src/ — the surface area is small. Read the whole tree, it's an afternoon at most.
3. vendor/orkestra/common/tests/ — if tests shipped, they are the only documentation you have. There is no docs site, no README worth the name, and no maintainer to ask.

First use case — a throwaway spike, not production. Wire it into a scratch Laravel app with Doctrine already working (laravel-doctrine/orm or a hand-rolled EntityManager binding), then exercise the one or two classes that motivated the install. Concretely, the realistic candidates are:

• an abstract entity base giving you an id, timestamps, or a __toString/equals() convention;
• value-object or enum-style helpers for typed scalar fields;
• inflector/string/math utilities that have nothing to do with Doctrine at all.

If your spike shows you need exactly two of those, stop depending on the package and copy those two classes into app/Support/ with a license header. That is almost certainly the right outcome for a 1-star, 11-year-stale library.

Where to look first in a Laravel codebase: nowhere in the HTTP layer. This belongs behind a repository or in app/Doctrine/, and only if you have already committed to Doctrine ORM over Eloquent. If your app is Eloquent-first, there is no day-to-day leverage here — skip it.

Implementation Patterns

Extend, but only once. If the package offers an abstract entity, remember PHP gives you one parent. Prefer to consume its behaviour via traits or by extracting the few methods you want, otherwise you've spent your inheritance budget on a library you'll want to remove in a year.

// app/Doctrine/Entity/AbstractEntity.php — your own base, informed by theirs
abstract class AbstractEntity
{
    use IdentifiesItself;   // id + equals()
    use TimestampsItself;   // createdAt / updatedAt
}

Keep the dependency at the edge. The pattern that ages well: your domain entities and repositories know nothing about Orkestra\*. A thin adapter in app/Doctrine/ calls into the package; when you drop it, you edit one file.

namespace App\Doctrine;

final class EntityFactory
{
    public function __construct(private \Doctrine\ORM\EntityManagerInterface $em) {}

    public function make(string $class): object
    {
        // whatever convention the package encodes goes here, not in your domain
        return new $class();
    }
}

Value objects + Doctrine custom types. If you're using the package's scalar/enum helpers for things like order status or currency, map them through a DBAL custom type rather than converting in every repository method:

#[ORM\Column(type: 'order_status')]
private OrderStatus $status;

Register the type in your Doctrine bootstrap (Type::addType(...) / $config->setCustomTypes()), which in Laravel means inside whichever service provider owns the EntityManager.

Testing pattern — in-memory SQLite + SchemaTool. Because the package has no test harness of its own, validate any entity base you adopt by asserting the mapping builds:

$em = /* in-memory sqlite EM with your entities */;
(new SchemaTool($em))->createSchema($em->getMetadataFactory()->getAllMetadata());
$this->assertTrue(true);

This flushes out annotation/attribute incompatibilities with whatever Doctrine version you actually resolved.

Integration tip — pin hard. Add an exact version and commit composer.lock. If you need a bugfix (and you will), fork to a private VCS repo and point at your fork:

"repositories": [{ "type": "vcs", "url": "[email protected]:you/orkestra-common.git" }],
"require": { "orkestra/common": "dev-master" }

Migration pattern. If you're inheriting a codebase already using it, don't rip it out in one go — introduce your own base classes that mirror the package's API, make your entities extend those, and swap the internals later. The call sites don't move.

Gotchas and Tips

The Doctrine\Common\Persistence namespace is the landmine. Code from 2014 very likely type-hints Doctrine\Common\Persistence\ObjectManager or ManagerRegistry. Those interfaces were removed from doctrine/persistence 2.x and now live in doctrine/orm under Doctrine\ORM\* / moved packages. If you upgrade Doctrine on a modern stack, you'll get Class not found at runtime, not at composer-install time. Grep the vendor tree for Common\Persistence before you commit:

grep -rn "Common\\\\Persistence" vendor/orkestra/common/src

PHP version drift. A 2014 package predates PHP 7 return types, nullable types, and PHP 8's dynamic-property deprecation. It may emit deprecation notices on PHP 8.1+ or, worse, silently rely on loose comparison changes. Run the test suite (if any) and a php -l sweep, and set error_reporting(E_ALL) in a staging run before trusting it in production.

No PHP 8 attributes. If the entity code uses Doctrine annotations (@ORM\Column), you'll need doctrine/annotations still installed and registered — modern Doctrine defaults to attributes, so annotation-based mapping will silently produce "no mapped fields" errors. Check src/ for @ORM strings.

Autoload mismatch bites when you subclass. If it's PSR-0, adding Orkestra\Common\SomeThing under your app/ directory won't resolve the way a PSR-4 namespace does. Register your own namespace separately; don't try to extend theirs by file placement.

Debugging SQL. The usual Doctrine tooling still applies and is the fastest way to see whether the package's helpers are generating sane queries:

$em->getConfiguration()->setSQLLogger(new \Doctrine\DBAL\Logging\DebugStack());

Inspect $logger->queries after the request. If an abstract entity's __toString() or equals() triggers a lazy load you didn't expect, this is where you'll spot it.

Traps in identity/equality helpers. If the package provides an equals() implementation, verify whether it compares by database identifier or by object identity. Comparing null === null for two unsaved entities makes equals() return true for any two new objects — a classic source of "why did my collection dedupe incorrectly" bugs. Write an explicit test for the unsaved case.

Extension points are Doctrine's, not the package's. Don't hunt for hooks. Use Doctrine event subscribers (prePersist, onFlush, loadClassMetadata) and lifecycle callbacks for anything the package doesn't cover — that's the supported seam, and it survives you dropping the library.

Watch for global state. Utility libraries of this era often rely on static registries or singletons (type registries, inflector configuration). Static state is invisible in Laravel's container and will leak between tests. If you see ::add calls in the constructor path, isolate them in a setUp/tearDown or avoid the class entirely.

Verdict to keep in mind day-to-day: with 1 star, 0 dependents, and a last release over a decade old, there is no upgrade path and no security response. Use it as a reference implementation to copy from, or as a temporary bridge during a migration — never as a load-bearing dependency in a new Laravel application. If a review asks "why do we depend on this?", the answer should be a link to your fork, not to Packagist.