Doctrine Timestamp Laravel Package

Getting Started

This is a major release (2.0.0) with two meaningful changes: the package now requires PHP 8+, and its primary API changed from a class to a trait. That second change is breaking: existing code that instantiated, extended, or type-hinted the old class will no longer work as-is.

Start here:

1. Read the package's UPGRADE.md / CHANGELOG.md for the exact old class name and new trait name.
2. Confirm your app and CI run PHP 8.0+ (php -v, composer.json require.php, CI matrix).
3. Locate every reference to the old class in your codebase:

   grep -R "Vendor\\Package\\OldClass" app/ config/ tests/
   

4. Replace usage with the trait. If the old usage looked like this:

   use Vendor\Package\OldClass;
   
   class MyService extends OldClass
   {
   }
   

   the new usage will look like this:

   use Vendor\Package\NewTrait;
   
   class MyService
   {
       use NewTrait;
   }
   

First practical use case: add the trait to the class where you previously used the package class, then run that class's existing tests. This validates method availability before you refactor the rest of the integration.

Implementation Patterns

Compose the trait into your own class. The 2.0 API expects you to own the class and pull package behaviour in:

namespace App\Services;

use Vendor\Package\PackageTrait;

class ReportGenerator
{
    use PackageTrait;

    public function generate(): array
    {
        return $this->packageMethod();
    }
}

Use trait aliasing when method names collide. This is common when moving from a base class to a trait:

use Vendor\Package\PackageTrait {
    packageMethod as protected packageMethodAliased;
}

Prefer dependency injection at the boundary. If the trait exposes behaviour used across the app, wrap it in a small application service rather than sprinkling use PackageTrait through controllers, models, and jobs:

class ShippingCalculator
{
    use PackageTrait;

    public function quote(Order $order): Money
    {
        return $this->calculate($order);
    }
}

Then inject ShippingCalculator wherever needed. This keeps the package boundary in one place and makes future major upgrades cheaper.

Refactor old inheritance and instantiation. If 1.x code did new OldClass(...) or extends OldClass, move construction concerns into your own class constructor and call trait methods from there. If it did app(OldClass::class), replace that with your own service binding:

// app/Providers/AppServiceProvider.php
$this->app->singleton(ShippingCalculator::class);

Update tests to reflect the new shape. Tests that mocked or instantiated the old class should now instantiate the class using the trait, or mock your wrapper service. If the trait has dependencies, set them through your class constructor.

Run PHP 8 compatibility checks across the integration. The package requires PHP 8, so your app must too. Check composer.json, Docker images, and CI. Also confirm your Laravel version supports PHP 8 (Laravel 9+ requires PHP 8.0; Laravel 8 supports it on recent patch releases).

Gotchas and Tips

• This is a breaking change, not a drop-in upgrade. Moving from class to trait changes inheritance, construction, type-hinting, and mocking. Treat 2.0 as a refactor, not a composer update.
• Traits cannot be type-hinted or resolved from the container. Any OldClass $dependency type hints must be replaced with your own class or interface.
• Watch for constructor removal. If the old class had a constructor that accepted config or dependencies, that setup now belongs in the class using the trait.
• Trait method conflicts fail at class definition time. If your class already defines a method with the same name, PHP will fatal. Alias or rename explicitly.
• Visibility changes are easy to miss. A trait method may be public where the old class method was protected, or vice versa. Check call sites after upgrading.
• Static and self:: behaviour can shift. Traits are flattened into the using class, so self:: and static:: resolve to your class. Verify anything relying on late static binding.
• PHP 8 upgrade may surface unrelated issues. Union types, named arguments, and stricter comparisons in your own code can behave differently once the runtime changes. Run the full test suite, not just package-related tests.
• Check package Laravel constraints. Confirm composer.json allows your Laravel version alongside PHP 8; a PHP bump alone does not guarantee framework compatibility.
• Use the trait as an extension point, not a dumping ground. Override trait methods in the using class where you need custom behaviour, but keep overrides thin and documented.
• Debugging tip: if methods appear missing, confirm the trait is imported (use Vendor\Package\PackageTrait; inside the class body) and not just imported as a namespace at the top of the file. These two use statements are easy to confuse during the migration.