DEV Community: ΠR

How Doppar Will Solve Your PHP Problem and Can Be Your Go-To Framework

ΠR — Sun, 18 Oct 2026 13:59:11 +0000

Every PHP team I know has the same short list of problems. Somebody needs to know what a record looked like last month. A lock is never released when a job throws. An email goes out for an order that was rolled back a second later. A service gets changed in the middle of a request and nobody can say where. A search box finds nothing because the customer typed "backpack" and the product says "daypack".

You can solve each of these. The question is how much code, how many packages and how many late nights it costs you.

Doppar is a PHP framework built around a simple idea: those problems are common enough that the framework should handle them for you. This post walks through 20 features that show what that looks like. For each one I'll tell you what it is, why you'd use it, and show a short example, the same way you'd explain defer() to a colleague.

A quick word on ordering. The first group is made of features that are unusual. As far as I know, you won't find them built into the core of Laravel or Symfony. Some of the ideas exist elsewhere as packages or in a different shape, so I'll be fair about that as we go. The second group is everyday stuff that Doppar does well and makes pleasant.

Doppar 4.x needs PHP 8.5. Where a feature arrived in a specific release, I say so.

Part 1: The features that make Doppar different

1. Temporal ORM: ask what a record looked like last month

What it is. Add one attribute to a model, and Doppar keeps a full history of every create, update and delete. You can then ask what a record looked like at any point in time, compare two moments, or roll a record back.

Why you'd use it. Audit trails, "who changed this price?", undoing a bad edit, legal records. Normally this means a second table, a pile of observers and a lot of care. Here it's one line.

use Phaseolies\Database\Temporal\Attributes\Temporal;

#[Temporal]
class Contract extends Model
{
    protected $table = 'contracts';
    protected $creatable = ['title', 'status', 'amount'];
}

Run php pool migrate:temporal once to create the history table. After that:

$then = Contract::at('2024-01-01')->find(42);     // the contract as it was
echo $then->status;                                // 'draft'

$diff = $contract->diff('2024-01-01', '2024-06-01');
// ['changes' => ['status' => ['from' => 'draft', 'to' => 'active']], ...]

$contract->restoreTo('2024-01-01');                // roll it back, and the restore is recorded too

Every change goes through the model's normal save(), so the restore is itself recorded as a new entry in the history.

2. Frozen services: configuration that cannot be changed behind your back

What it is. Mark a service with #[Immutable]. You configure it while the app boots, and from the first time the container hands it out, any write to it throws an exception.

Why you'd use it. Singletons that hold settings (a payment gateway, a tax rate) are shared by the whole process. One careless $payment->taxRate = 0 in a controller and every user is affected. A frozen service turns that quiet bug into a loud one, at the exact line that caused it.

#[Immutable]
class PaymentService
{
    use EnforcesImmutability;

    public string $gateway = 'stripe';
    public float  $taxRate = 0.08;
}

// In a launcher, while the app boots
$payment = new PaymentService();
$payment->gateway = config('payment.gateway');

$this->app->singleton(PaymentService::class, fn () => $payment);

Later, anywhere in your app:

$payment->charge(100);        // fine
$payment->taxRate = 0.0;      // throws ImmutableViolationException

Reading, method calls and isset() always work. Writes, unset() and clone throw. Freezing closure and instance() services arrived in Doppar 4.7.0.

3. Reactive models: react to one property, not the whole save

What it is. #[Watches] lets you attach a small class to a single property. When that property changes and the save succeeds, Doppar calls your class with the old value, the new value and the model.

Why you'd use it. "Do something when the order status changes" is everywhere. Without this you write a model event, check which fields are dirty, compare values, and repeat it for every property.

class Order extends Model
{
    protected $creatable = ['user_id', 'status', 'total'];

    #[Watches(OrderStatusChanged::class)]
    protected $status;
}

class OrderStatusChanged
{
    public function handle(mixed $old, mixed $new, Model $model): void
    {
        if ($new === 'shipped') {
            // tell the customer
        }
    }
}

You can stack several watchers on one property, watch several properties, and make a watch conditional.

4. Semantic search with one attribute, and no API key

What it is. The doppar/embeds package adds #[Embeds]. Mark a column, and Doppar keeps a numeric representation of its meaning up to date every time you save. You then search by meaning instead of by words.

Why you'd use it. LIKE '%backpack%' will never find "rugged daypack for hiking in the rain". Meaning-based search will. The model runs on your own server, so there is no external API, no key and no per-request cost.

class Product extends Model
{
    use Embeddable;

    protected $creatable = ['name', 'description'];

    #[Embeds]
    protected $description;
}

$results = Product::whereSimilarTo('description', 'a durable waterproof backpack', limit: 10);

You get a collection of products ordered from most to least similar. You never call an embedding function yourself. Setting the property and saving is enough. There are three storage drivers: brute_force, pgvector and redis. Note that it needs PHP's FFI extension turned on for persistent servers like PHP-FPM, and the docs explain how.

5. `#[Transaction]`: wrap a controller action in a transaction with one line

What it is. An attribute that runs your controller method inside a database transaction, with optional retries.

Why you'd use it. Most "create an order and its items" actions need a transaction. Writing DB::transaction(...) around the whole body is easy to forget and makes the code nest deeper.

use Phaseolies\Database\Attributes\Transaction;

#[Transaction(attempts: 3)]
#[Route(uri: 'orders', methods: ['POST'])]
public function store(Request $request)
{
    $order = Order::create($request->all());
    // ...
}

If the method throws, the transaction rolls back. With attempts: 3, a transient failure such as a deadlock is retried up to three times. You can also pick a connection: #[Transaction(connection: 'pgsql')].

6. Templates where you choose the syntax

What it is. Odo is Doppar's template engine. It compiles to plain cached PHP, and every delimiter (directives, echo tags, comments) can be changed in one config file.

Why you'd use it. If a project already uses a syntax that clashes with {{ }} (some JavaScript frameworks do), or you simply prefer another style, you change a config value and carry on. Output is escaped by default.

#if ($user)
    <h1>[[ $user->name ]]</h1>
#endif

#foreach ($posts as $post)
    <p>[[ $post->title ]]</p>
#endforeach

Don't like # for directives? Set 'directive_prefix' => '@' in runtime/config/odo.php and write @if and @foreach instead.

7. A Bloom filter you can call from your code

What it is. The doppar/bloom package gives you a Bloom filter backed by Redis. It answers "is this probably in the set?" using a small fixed amount of memory.

Why you'd use it. "Have I seen this email or URL before?" without a database query. According to the docs, memory stays around 12.5 MB whether you hold 100,000 items or 10 million, and checks take a fraction of a millisecond. The trade-off is that it can say "probably yes" but never a wrong "no".

if (Bloom::key('email')->add($email)) {
    // probably seen before
} else {
    // definitely new
}

Bloom::key('email')->has('someone@example.com');

8. A queue that survives crashes and kills stuck jobs

What it is. doppar/queue runs your background jobs on the database or on Redis. It has priorities, unique jobs, retry backoff, and a lease system for recovery.

Why you'd use it. The usual queue nightmares: a worker dies and the job is lost or stuck, or a job hangs forever and blocks the worker. Here, a worker holds a lease on a job. If the worker dies, the lease runs out and another worker takes the job, with its attempt count kept. A job that sets a timeout runs in its own process, so a stuck job gets killed instead of hanging the worker.

#[Queueable(timeout: 60, priority: 90)]
class SendPasswordResetJob extends Job
{
    public function __construct(public User $user) {}

    public function handle(): void
    {
        // runs in its own process, stopped after 60 seconds
    }
}

Give a job a key and a second copy is refused while the first one waits or runs:

public function uniqueId(): ?string
{
    return (string) $this->reportId;
}

Because a job can run twice after a crash, write jobs so that running them again is safe. The docs say the same.

Part 2: Features that make everyday work better

9. Model hooks: put model rules next to the model

What it is. Attach small methods to moments in a model's life: before it is created, after it is deleted, and so on. Use the #[Hook] attribute on a method.

Why you'd use it. Slugs, default values, cache clearing and audit records belong with the model, not scattered across controllers where one of them will forget.

class Post extends Model
{
    #[Hook('before_created')]
    public function generateSlug(): void
    {
        $this->slug = str()->slug($this->title);
    }

    #[Hook('before_updated', when: 'isBeingPublished')]
    public function stampPublishedAt(): void
    {
        $this->published_at = now();
    }

    public function isBeingPublished(): bool
    {
        return $this->isDirtyAttr('status') && $this->status === 'published';
    }
}

There are ten events. If you need to write without hooks (an import, a data fix), $post->withoutHook()->save() skips them for one write. In 4.7.0, withHooks() was added for the opposite case: Post::where('status', 'draft')->withHooks()->update([...]) runs the hooks for every record in a bulk update.

10. Execution context: one identity for every request, command and job

What it is. Every piece of work in Doppar (an HTTP request, a console command, a queue job) runs inside an execution with its own id, type and metadata. Services can be tied to that execution, so they disappear with it.

Why you'd use it. In a long-running worker, a singleton that holds "the current tenant" will leak into the next job. And when something fails, you want one id that ties together every log line from that request. Both are solved here.

Execution::id();                       // "9f2c41e07b1d3a58"
Execution::type();                     // "request"

Execution::stamp(['tenant' => 'acme']);
Log::error('Payment failed');          // the log entry carries the id, type and tenant

For per-request state, bind the service to the execution scope, and it can never be seen by the next request:

$this->app->bindExecution(TenantState::class, fn () => new TenantState());

This arrived in Doppar 4.6.0.

11. `defer()`: clean up right where you create the mess

What it is. defer() works like Go's defer. You register a cleanup callback right after you acquire something, and Doppar runs it when the current execution ends, whether it succeeded or threw.

Why you'd use it. try/finally puts the release at the bottom, far from the acquire. Add a second resource and you nest another level.

$lock = cache()->locked('report:' . $id, seconds: 30);

if (! $lock->get()) {
    throw new \RuntimeException('Already running.');
}

defer(fn () => $lock->release());

$report = $this->generateReport($id);

Callbacks run in reverse order, one broken callback never stops the others, and the original exception is never replaced. It works in requests, console commands and queue jobs. One honest limit: if the process is killed (a job timeout kill, kill -9, a power cut), no PHP code runs, so give your locks their own expiry too. This arrived in 4.6.0.

12. Signals: events that wait for the commit

What it is. A signal is a small object that says "this happened". If you emit it inside a transaction, Doppar can hold it back until the transaction has really committed, and drop it if the transaction rolls back.

Why you'd use it. Nobody wants a receipt email for a payment that was rolled back.

#[DeliverOnSettle]
class InvoicePaid
{
    public function __construct(public readonly int $invoiceId) {}
}

DB::transaction(function () use ($invoice) {
    $invoice->markPaid();

    Signal::emit(new InvoicePaid($invoice->id));   // held until the commit
});

Nested transactions hand their signals up to the parent, each database connection settles on its own, and it all runs synchronously with no queue involved. Scaffold one with php pool make:signal InvoicePaid --settle.

13. Routing, binding and rate limits as attributes

What it is. Routes, route-model binding and throttling sit on the controller method, in plain sight.

Why you'd use it. You read the method and see everything about it: its URL, its limits and what it loads.

#[Route(uri: 'login', methods: ['POST'], rateLimit: 10, rateLimitDecay: 1)]
public function login(Request $request) { /* ... */ }

#[Route('/profile/{user}', methods: ['GET'], where: ['user' => '[0-9]+'])]
public function show(#[Model] User $user)
{
    // /profile/5 loads the user; /profile/abc is a 404 and never queries the database
}

#[Model('email')] binds on another column. There is also a #[Throttle(maxAttempts: 10, decayMinutes: 1)] attribute, and #[Mapper] for prefixes and middleware on a whole controller. If you prefer a routes file, the Route facade works too. Since 4.2.0 Doppar also reads each controller action once and caches the result, so routing does not use Reflection on every request.

14. Validate a request with a plain class

What it is. Describe your input as a small class with attributes, and Doppar validates the request before your controller code runs.

Why you'd use it. Your controller receives clean, typed data, or the request is rejected. There is no validation code in the action itself.

class BookData
{
    #[NotBlank]
    #[StringType]
    #[Length(max: 255)]
    public string $title;

    #[NotBlank]
    #[Integer]
    #[Between(min: 1, max: 5)]
    public int $rating;
}

#[Route(uri: 'books', methods: ['POST'])]
public function store(#[BindPayload(strict: true, validate: true)] BookData $book)
{
    Book::create($book->toArray());
}

15. Soft deletes and casts, without traits

What it is. Two common model features, switched on with attributes.

Why you'd use it. No trait to remember, no global scope to register, and the setup is visible at a glance.

#[SoftDeletes]
class Post extends Model
{
    #[ToBoolean]
    protected string $is_featured;

    #[ToDateTime]
    protected string $published_at;
}

With #[SoftDeletes], delete() marks the row as deleted, and every query leaves trashed rows out unless you ask: withTrashed(), onlyTrashed(), restore(), forceDelete(). Casts work on read and write, so you stop scattering (bool) and json_decode() through your code.

16. Relationships with names that say what they do

What it is. Doppar names relationships by what they do: linkOne, linkMany, bindTo for the inverse, and bindToMany for many-to-many. You load them with embed(), and you can choose the columns.

Why you'd use it. Eager loading without the N+1 problem, and without loading columns you don't need.

class User extends Model
{
    public function otp()
    {
        return $this->linkOne(Otp::class, 'user_id', 'id');
    }
}

$user = User::find(1)->otp;                    // lazy loading

User::query()
    ->embed('otp', fn ($q) => $q->select('id', 'otp', 'user_id'))
    ->get();                                   // one extra query, only those columns

You can ask the other way too: User::present('otp') finds users that have one, User::absent('otp') finds those that don't, and embedCount() returns counts without loading the records. For many-to-many, link(), unlink() and relate() manage the pivot table for you.

17. Stream collections: process a huge file without running out of memory

What it is. A lazy collection built on generators. Each step (map, filter, take) runs only when you actually read the data.

Why you'd use it. Reading a 2 GB log file into an array is a good way to crash a server. A stream reads one line at a time.

$errors = StreamCollection::lines(storage_path('logs/app.log'))
    ->filter(fn ($line) => str_contains($line, 'ERROR'))
    ->take(10)
    ->all();

The file is opened when you start reading and closed when the stream ends, or when you stop early, as take(10) does here.

18. Run system commands without opening a security hole

What it is. doppar/orion runs shell commands, in sequence, in parallel pools, or piped into each other. It is built on Symfony Process.

Why you'd use it. Running commands from PHP is a classic place for command injection. Orion never runs your command through a shell, so $HOME, *, ; and | are just text.

$result = Process::ping('git commit -m "fix the bug"')->execute();

return $result->getOutput();

Process::ping('echo $HOME')->execute()->getOutput();   // "$HOME", the variable is not expanded

When an argument has awkward characters, pass an array and each element goes to the program exactly as it is.

19. A profiler built into your development loop

What it is. doppar/insight adds a toolbar to the page you are working on, plus a history of recent requests.

Why you'd use it. To see the SQL queries, cache hits, session data, logs and timing of a request without leaving the browser. It also shows status codes, response times and errors across several requests, which helps you spot the slow endpoint.

composer require doppar/insight

Register its launcher in runtime/config/app.php and you are done. It is meant for development, so don't leave it switched on in production.

20. AI that runs on your own server

What it is. doppar/ai has two parts. Pipeline runs machine-learning tasks locally (sentiment analysis, text generation and more, over 15 tasks in all) using models from Hugging Face. Agent talks to cloud models such as OpenAI or Gemini.

Why you'd use it. You can add features like sentiment analysis without sending your customers' text to anyone, and without a per-call bill. Use the cloud agents when you need a bigger model.

$result = Pipeline::execute(
    task: TaskEnum::SENTIMENT_ANALYSIS,
    data: 'I absolutely love this product! Best purchase ever!'
);
// [['label' => 'POSITIVE', 'score' => 0.9998]]

$answer = Agent::using(OpenAI::class)
    ->withKey(env('OPENAI_API_KEY'))
    ->model('gpt-3.5-turbo')
    ->prompt('Explain quantum computing in simple terms')
    ->send();

A few smaller things that add up

env.toml instead of .env. Your configuration file has real types: booleans and numbers are not strings that you cast.
php pool. One console for everything, with generators such as make:job, make:signal, make:watcher, make:hook and make:presenter.
API presenters. A dedicated class that decides what your JSON looks like, so your models never leak columns by accident.
Launchers. In 4.x, service providers became launchers: register() and launch(), in src/Launchers.
Speed. The Doppar docs report about 2,100 requests per second on a tiny endpoint (one User::find(1)) with Nginx, PHP-FPM and PHP 8.5, in one local run. Treat that as one data point from the authors, not a promise for your app. Measure your own.

So, should it be your go-to framework?

Here is my honest take.

Pick Doppar if you like the features above and want them in the core, working together, instead of hunting for six packages. It's a good fit if you read code more than you write it, because attributes put the important facts right on the class or method. It's also a good fit if you run workers and long-lived processes and you're tired of state leaking between jobs.

Think twice if your team depends on a huge third-party ecosystem, or you need a framework with a decade of Stack Overflow answers. Laravel and Symfony are excellent, and they have that. Doppar is younger and its community is smaller. It also needs PHP 8.5, so check your hosting first.

The best way to decide is to try one feature. Take the problem that annoyed you most this month (history, cleanup, commit-safe emails, frozen config, search) and build that one thing in Doppar. If it feels easier than what you have today, you'll know.

The full documentation is at https://doppar.com/versions/4.x/installation, and you can see what's new in 4.x at https://doppar.com/versions/4.x/releases.

Doppar 4 Has Been Released, and Here Is Why It Is Special

ΠR — Sun, 20 Sep 2026 17:28:06 +0000

Doppar 4.0 is out today.

I want to start this post with something I haven't said out loud before. Doppar 3.0 was a good framework, but if you put it next to Laravel, a lot of people could not tell where one ended and the other began. Service providers with register() and boot(). An App\Http\Kernel. resource_path() and database_path(). A .env file. An app/ folder. Familiar names have a real upside, because they make a new framework easy to try. They also mean the framework is wearing somebody else's t-shirt.

With 3.0 we wore the Laravel t-shirt. With 4.0 we took it off.

That is the short version of why this release matters to me. The long version is the rest of this post, and it is long, because 4.0 touches almost everything a Doppar developer sees in a day: the folder layout, the bootstrapping classes, the config file, the mailer, the path helpers, the attribute imports at the top of every controller. If you are running 3.x, please read all of it before you upgrade. If you are new to Doppar, this is a good place to start, because the framework finally looks like itself.

Why I wanted to change it

Here is the uncomfortable part. Under the surface, Doppar was never a Laravel clone. Models that keep their own history with #[Temporal] and let you time-travel a query. Services you can freeze with #[Immutable] so nothing mutates them after the container builds them. #[Watches] on a property to react to exactly the field that changed, with the old and new value. Casting done with attributes on the property itself instead of a string array. A queue worker that forks a child per job, so a job that hangs gets killed and the worker stays alive. Attribute-driven routing from day one.

None of that came from anywhere else. But when you opened a 3.x project, the first thing you saw was the vocabulary of another framework, and the vocabulary sets the expectation. People read ServiceProvider and assumed the rest would behave the same. Sometimes it did. Often it didn't, and that was confusing for them and unfair to the framework.

So for 4.0 the rule was simple: if a name, a folder, or a convention exists only because another framework has it, question it. Some things survived. A lot didn't.

The 4.0 changes, one by one

1. PHP 8.5 is the minimum

Doppar 3.x needed PHP 8.3. Doppar 4.x needs PHP 8.5. There is no compatibility mode.

I know that is a hard line, and I thought about it for a while. But every version of PHP we support is a version we have to write around. PHP 8.5 brings the pipe operator, first-class Uri objects, clone() with property overrides, and the #[\NoDiscard] attribute. Some of those we can already lean on, others we will use as they settle in, and none of them would be available to the framework or to your application if we kept an 8.3 floor. Raising the minimum now means we don't carry a compatibility tax for the next several years.

The practical rule: upgrade your PHP runtime first, before you touch a single line of application code. Everything below assumes 8.5.

2. Providers are now Launchers

This is the biggest architectural change, and the one you will notice first.

Phaseolies\Providers\ServiceProvider is gone. In its place there is Phaseolies\Launchers\ServiceLauncher, and the two lifecycle methods are renamed to say what they do: register() stays, boot() becomes launch(). Your classes move from app/Providers to src/Launchers.

3.x

<?php

namespace App\Providers;

use Phaseolies\Providers\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        //
    }

    public function boot(): void
    {
        //
    }
}

4.x

<?php

namespace App\Launchers;

use Phaseolies\Launchers\ServiceLauncher;

class AppLauncher extends ServiceLauncher
{
    /**
     * Register any application services.
     *
     * @return void
     */
    public function register(): void
    {
        //
    }

    /**
     * Launch any application services.
     *
     * @return void
     */
    public function launch(): void
    {
        //
    }
}

The generator follows the rename:

# 3.x
php pool make:provider MyServiceProvider

# 4.x
php pool make:launcher MyLauncher

register() means what it always meant. That is where you put container bindings and raw service wiring. launch() is for anything that needs other services to already exist: loading routes, views, migrations, translations, console commands.

Why rename it at all? Because "boot" tells you nothing. A launcher registers its services, then launches. It is a small change in wording, but when you read a class called AppLauncher with a method called launch(), you know what it is for, and you are not translating from another framework's documentation in your head.

Launchers can also be ghostable, which means the framework registers them lazily the first time one of their declared services is actually resolved, instead of on every request. If a launcher provides something only 5% of your requests need, that 5% is the only place you pay for it.

Package authors, this affects you too. Publishable resources are declared inside launchers now, so the flag on vendor:publish changed:

# 3.x
php pool vendor:publish --provider="Vendor\PackageName\PackageServiceProvider"

# 4.x
php pool vendor:publish --launcher="Vendor\PackageName\PackageLauncher"

If your README still says --provider, your users will hit an unrecognized option error on 4.x.

3. The Kernel is now the Gateway, and the Router stopped extending it

In 3.x, Phaseolies\Support\Router extended your application's App\Http\Kernel. Think about what that means. A class inside the framework inherited from a class that lives in your app. The framework depended on your code, in the wrong direction.

In 4.x that is fixed. App\Http\Kernel becomes App\Http\Gateway, it implements a new GatewayInterface, and the Router depends on that interface instead of extending anything.

// 4.x — src/Http/Gateway.php
namespace App\Http;

use Phaseolies\Middleware\Middleware;
use Phaseolies\Http\Contracts\GatewayInterface;

class Gateway extends Middleware implements GatewayInterface
{
    public array $middleware = [/* ... */];
    public $middlewareGroups = [/* ... */];
    public array $routeMiddleware = [/* ... */];

    public function getGlobalMiddleware(): array
    {
        return $this->middleware;
    }

    public function getMiddlewareGroups(): array
    {
        return $this->middlewareGroups;
    }

    public function getRouteMiddleware(): array
    {
        return $this->routeMiddleware;
    }
}

Your three arrays keep exactly the same shape. Only the file name, the class name, and the interface are new. The framework still finds App\Http\Gateway by convention, so in the common case you don't bind anything by hand.

This one is not cosmetic, and I want to be clear about that. Once the router talks to an interface, you can swap the gateway in tests, and packages can build on the router without inheriting from something that belongs to the app. There is one side effect worth knowing about. Something that used to call applyMiddleware() directly on the router now has to go through the gateway. I ran into exactly this while fixing our own profiler package for 4.x, so if you maintain a package that registers global middleware, check for it.

4. A folder structure that belongs to Doppar

The whole skeleton was reorganised. Your application code lives in src/. Views and language files live in templates/. Migrations and seeders live in schema/. Configuration, routes, and the bootstrap file live in runtime/. The bootstrap/ folder is gone, and its work is done by runtime/app.php.

3.x	4.x
`app/`	`src/`
`app/Providers/`	`src/Launchers/`
`config/`	`runtime/config/`
`routes/`	`runtime/routes/`
`bootstrap/`	`runtime/app.php`
`database/migrations/`	`schema/migrations/`
`database/seeds/`	`schema/seeders/`
`resources/views/`	`templates/views/`
`lang/`	`templates/lang/`

storage/, public/, and tests/ stay where they were. The test folder now ships a BootstrapApplication.php next to TestCase.php.

I like this layout for a specific reason. Open a fresh 4.x project and each top-level folder answers one question. What is my code? src/. What does the framework need at runtime to start? runtime/. What describes my database? schema/. What does the user see? templates/. In the old layout config, routes, and bootstrap were three separate folders for what is really one concern.

Two path helpers changed to match, and they have no deprecated alias:

// 3.x
$view = resource_path('views/layouts/app.Odo.php');
$migrations = database_path('migrations/');

// 4.x
$view = template_path('views/layouts/app.Odo.php');
$migrations = schema_path('migrations/');

Search your project for every call. A leftover resource_path() or database_path() is a fatal error on 4.x, and I would rather you find it with a search than find it in production.

5. Attributes now live next to the thing they configure

In 3.x every attribute we ship lived in one flat namespace, Phaseolies\Utilities\Attributes. That is a junk drawer. #[Route] had nothing to do with #[Transaction], but they sat side by side.

In 4.x each attribute moved to the subsystem it belongs to:

Attribute	4.x namespace
`#[Bind]`, `#[Resolver]`	`Phaseolies\DI\Attributes`
`#[Transaction]`	`Phaseolies\Database\Attributes`
`#[Model]`	`Phaseolies\Database\Entity\Attributes`
`#[BindPayload]`	`Phaseolies\Http\Requests\Attributes`
`#[Middleware]`	`Phaseolies\Middleware\Attributes`
`#[Route]`, `#[Mapper]`, `#[Throttle]`	`Phaseolies\Support\Router\Attributes`

Every one of these is a namespace move and nothing else. Names, signatures, and behaviour are unchanged. All you do is fix the use line at the top of each controller, model, and middleware:

// 3.x
use Phaseolies\Utilities\Attributes\Route;
use Phaseolies\Utilities\Attributes\Middleware;

// 4.x
use Phaseolies\Support\Router\Attributes\Route;
use Phaseolies\Middleware\Attributes\Middleware;

One attribute did not move, it was removed: #[CastToDate]. It was deprecated in favour of the attribute cast system (#[ToDate] and friends), and in a major version we finish what we announced. If any of your models still use it, delete the import and the line.

6. `env.toml` replaces `.env`

This is my favourite small change in the release, because it fixes a bug that every PHP developer has hit at least once.

A .env file only produces strings. APP_DEBUG=false is not the boolean false. It is the five-character string "false", and in PHP (bool) "false" is true. So a debug flag you turned off stays on, and you find out when you see a stack trace on a live site.

4.x reads configuration from env.toml, and TOML has real types:

# env.toml
APP_NAME = "Doppar"
APP_ENV = "local"
APP_DEBUG = false
APP_URL = "http://localhost:8000"

DB_CONNECTION = "mysql"
DB_PORT = 3306

env('APP_DEBUG') returns an actual bool. env('DB_PORT') returns an actual int. You can stop writing (bool) env(...) and hoping.

A few things behave differently from what you're used to:

Strings must be quoted. APP_ENV = "local", not APP_ENV = local. Booleans and numbers are written bare.
The file must stay flat. TOML supports [section] tables, but every env() call expects a flat key, so Doppar rejects a nested table with a clear error instead of silently ignoring it.
No interpolation. MAIL_FROM_NAME="${APP_NAME}" has no equivalent. Write the literal value.
Real environment variables still win. If APP_DEBUG is already set at the process level (Docker, systemd, your host's panel), the value in env.toml is skipped for that key, exactly like .env always worked.

If env.toml is missing entirely, Doppar still boots and falls back to whatever real environment variables exist. That is handy for containers where configuration is injected and no file is shipped.

Remember to update your .gitignore too: .env becomes env.toml, and !.env.example becomes !env.toml.example.

7. Symfony Mailer replaces PHPMailer

Mail now runs on Symfony Mailer. PHPMailer is gone from the framework.

What does not change is what you actually write. Mailables keep their contract: subject(), content(), attachment(). The make:mail stub is the same. If your code only builds mailables and sends them, you may not need to touch it at all.

What does change:

runtime/config/mail.php needs updating. The qmail and plain mail (PHP's mail()) mailers are gone, because Symfony Mailer doesn't support them. Move to smtp, sendmail, or a DSN-based provider bridge.
Custom drivers need a rewrite. A class implementing MailDriverInterface should now be a Symfony TransportInterface.
CC and BCC really deliver now. Under the old behaviour they were not always handed to the SMTP server as real envelope recipients. If anything downstream relied on that, check it.

The nicest part is the DSN. One value replaces a whole block of host, port, username, and password settings:

MAILER_DSN = "smtp://user:pass@smtp.mailgun.org:587"

failover and roundrobin transports are supported too, if you want more than one provider behind a single mailer.

In composer.json, swap phpmailer/phpmailer for symfony/mailer: ^8.1.

8. Validate DTOs with attributes

This one is new, and I think it is going to change how many of you write controllers.

You already had #[BindPayload] to turn a request into a typed DTO. In 4.x you can also say what a valid payload looks like, on the properties themselves:

<?php

namespace App\DTO;

use Phaseolies\Validation\Attributes\Between;
use Phaseolies\Validation\Attributes\Integer;
use Phaseolies\Validation\Attributes\Length;
use Phaseolies\Validation\Attributes\NotBlank;
use Phaseolies\Validation\Attributes\StringType;

final class BookData
{
    #[NotBlank]
    #[StringType]
    #[Length(max: 255)]
    public string $title;

    #[NotBlank]
    #[Integer]
    #[Between(min: 1, max: 5)]
    public int $rating;
}

Then switch validation on where the DTO is bound:

#[Route(uri: 'books', methods: ['POST'])]
public function store(
    #[BindPayload(strict: true, validate: true)]
    BookData $book,
) {
    Book::create($book->toArray());

    return redirect('/books');
}

The payload is validated before the DTO is hydrated and handed to your controller. If the input is bad, your method never runs. The rules live next to the data they protect, so when someone changes the DTO they see the rules in the same file. The built-in constraints are #[NotBlank], #[StringType], #[Integer], #[Length], and #[Between].

9. Semantic search with `doppar/embeds`

4.0 ships a new package, doppar/embeds, that adds semantic search to your models with an attribute.

use Phaseolies\Database\Entity\Model;
use Doppar\Embeds\Attributes\Embeds;
use Doppar\Embeds\Concerns\Embeddable;

class Product extends Model
{
    use Embeddable;

    #[Embeds]
    protected $description;
}

$results = Product::whereSimilarTo('description', 'a durable waterproof backpack', limit: 10);

Mark a column with #[Embeds] and Doppar keeps a numeric representation of its meaning, a vector, in sync as records change. A search for "a durable waterproof backpack" then finds "rugged daypack for hiking in the rain", even though the two share almost no words. A plain LIKE query will never do that.

Two design decisions I care about. First, embeddings are computed locally through doppar/ai, so there is no external API call, no API key, and no per-request bill. Second, storage and ranking are handled by a swappable driver. The default brute_force driver needs no setup and works on every database Doppar supports. When a table gets large, pgvector and redis push the ranking into a real HNSW index.

All three drivers have been tested end to end against real data, including checking that the ranking results made sense and not only that the code ran. If you use the redis driver, read the package documentation first: it needs Redis Stack with the search module, and the module has a minimum Redis version. Loading it into an older Redis can take the server down. That is written down in the docs so you don't find out the hard way.

10. A security pass across the core

I am putting this near the end on purpose, because it is the change that matters most and gets talked about least.

While preparing 4.0 we went through the framework looking for the kind of problems that only show up when someone hostile reads your code. We found some, and fixed them:

Encryption moved to authenticated AES-256-GCM. New data is encrypted with an AEAD cipher, so tampering is detected instead of silently decrypting to garbage. Data encrypted with the old AES-256-CBC format still decrypts, so you don't lose anything. Along the way we fixed a bug in how the APP_KEY was decoded.
Path traversal was closed in Storage and in Support\File.
Upload validation looks at the real file. The mimes rule now inspects file content, so a script renamed to photo.jpg and sent with a friendly Content-Type header no longer passes. It fails closed: if PHP has no way to detect the type (the fileinfo extension is missing, for example), the file is rejected instead of trusted. Make sure fileinfo is enabled on your server.
SQL identifier injection was closed in the query builder. Column names and sort directions that reach the builder are now validated, and a sort direction that isn't ASC or DESC throws.
Mass assignment on update() is now protected the same way as create(). Updates only write attributes listed in the model's $creatable, and a model that doesn't declare $creatable throws a RuntimeException when you save it. This one can bite during an upgrade, so check your models: if any of them has no $creatable, add it before you go live.
The session ID is regenerated after a successful login, which closes the door on session fixation.

And a group of ordinary bugs that were not security issues but were bad enough to deserve a fix in a major release: Schema::table() was generating CREATE TABLE instead of ALTER TABLE, a dependency-injection resolution-order bug, Model::__get() swallowing a \Throwable, after_created hooks running in the wrong order, PostgreSQL enum validation, and base_path() handling of absolute paths on different platforms.

If you're on 3.x and cannot upgrade yet, take security seriously and follow the support policy below. If you can upgrade, this alone is a good reason to.

11. Smaller things, all deliberate

A redesigned error page. It shows the message, the request (method, URL, date, status code), and a code frame with the failing line highlighted, along with a light and dark toggle and a copy button.
Request no longer reads superglobals in its constructor. It takes its data as explicit arguments now, and Request::capture() builds one from the current PHP request. This makes requests far easier to construct in tests. If you create a Request by hand anywhere, pass the data in.
No global BASE_PATH constant. The base path is injected into the application through its constructor.
vendor:publish asks which launcher to publish when there is more than one, instead of guessing.
CI runs on PHP 8.5.

What this means for you

If you have a 3.x application, the upgrade touches every layer of it, and I won't pretend otherwise. The changes are mostly mechanical, but they are everywhere. Here is the order I would do it in. Each step assumes the one before is finished.

Upgrade PHP to 8.5 or later. Nothing else works without it.
Move the skeleton. app/ to src/, database/ to schema/ (and seeds/ to seeders/), resources/ to templates/, config/ to runtime/config/, routes/ to runtime/routes/, and fold bootstrap/ into runtime/app.php.
Convert every provider to a launcher. Move the files, extend ServiceLauncher, rename boot() to launch(), and update the launchers array in runtime/config/app.php.
Rename the path helpers. resource_path() to template_path(), database_path() to schema_path().
Fix the attribute imports, and remove any #[CastToDate].
Rename Kernel to Gateway and implement GatewayInterface.
Update vendor:publish flags in scripts and docs: --provider becomes --launcher.
Convert .env to env.toml. Quote strings, write booleans and numbers bare, flatten any ${VAR} interpolation, and fix .gitignore.
Swap the mail transport. Remove phpmailer/phpmailer, add symfony/mailer, update mail.php, and rewrite any custom driver.
Check your models and your server. Every model you save needs a $creatable list, and file uploads validated with mimes need the fileinfo PHP extension.
Run your tests. CC and BCC delivery changed, and anything that constructs a Request by hand needs to pass its data in.

Do all of this on a dedicated branch, and don't mix it with feature work. The launcher rename and the folder move are mechanical, but they touch nearly every file. A clean diff is much easier to review than a mixed one.

The complete step-by-step guide is in the release notes at doppar.com/versions/4.x/releases, and the installation guide is the place to start a fresh project.

Support and versioning

Doppar ships one major version a year, with minor and patch releases as needed in between. Minor releases don't break anything. Patch releases are bug fixes and security fixes. Constraints like ^4.0 are safe to use.

Each major version gets bug fixes for 18 months and security fixes for 24 months. 3.x keeps receiving bug fixes until June 1, 2027 and security fixes until December 1, 2027, so nobody is being forced to upgrade this week. The exact dates for 4.x are in the release notes table.

If you are starting something new, start on 4.0. If you're on 3.x, you have time, and I would use it to plan the upgrade properly instead of rushing it.

What I hope 4.0 is

I said at the top that we took off the Laravel t-shirt. I should be fair about it: I have nothing against the framework that shaped how a generation of PHP developers work. Its ideas made PHP better for everyone, including us. But a framework that only feels familiar has no reason of its own to exist. It needs its own words for things, its own layout, its own opinions, and a reason for you to choose it.

ServiceLauncher, Gateway, template_path(), schema_path(), runtime/, env.toml. These are small words. Together they say: this is Doppar, it has its own way of doing things, and it is confident enough to say so.

Thank you to everyone who filed an issue, sent a pull request, or asked a hard question in the last year. A lot of what is in 4.0 started as somebody saying "this doesn't make sense." You were right.

One more thing: Ripple is coming next week

I've been saving this for the last page.

Next week we are releasing Ripple, a new first-party package that lets you build interactive interfaces in PHP, without writing a JavaScript application on top of your Doppar app. I'll go through how it works here, because I've been reading the source this week and I'm excited about it.

If you've used a server-driven UI library before, you will recognise the shape. The idea is not new, and I won't pretend it is. What's ours is how it is built, and that it is a native Doppar package rather than a port.

You write a component as a PHP class and a view in Odo. The browser calls actions on it. Ripple runs your PHP, re-renders on the server, and sends back only the parts of the page that changed.

Here is the whole counter:

<?php

namespace App\Ripple;

use Doppar\Ripple\Attributes\Invokable;
use Doppar\Ripple\Component;

class Counter extends Component
{
    public int $count = 0;

    #[Invokable]
    public function increment(): void
    {
        $this->count++;
    }

    public function render(): mixed
    {
        return view('ripple.counter');
    }
}

<div>
    <p>Count: [[ $count ]]</p>
    <button type="button" ripple:call="increment">+</button>
</div>

Public properties are the component's state. Methods the browser is allowed to call are marked with #[Invokable], and only those. You mount it on any page with one line, or make it the entire page with a route:

Route::ripple('/counter', \App\Ripple\Counter::class)->name('counter');

How it works

When you click that button, five things happen:

The browser sends the action and the component's signed state to /ripple/update.
Ripple hydrates the component from that state and runs increment().
It renders the view again.
It compares the old HTML with the new HTML, and works out the smallest set of changes.
It sends those changes back and the browser applies them.

Step 4 is the interesting part. Ripple parses the rendered HTML into a lightweight virtual tree, walks the old tree and the new tree together, and produces a list of operations: replace a node, update some attributes, set some text, insert, remove, reorder. Only that list goes over the wire. Many tools in this space send the new HTML and let the browser figure out what changed. Ripple does the diff on the server, so the browser's job is just to apply a short list of instructions. The JavaScript client is about 12 KB minified, and you never have to build or configure it. Ripple copies it into public/ for you and you add one line to your layout.

Security was a design input, not a patch

State travels through the browser, so it has to be treated as untrusted. Ripple signs every component's state with an HMAC-SHA256 signature, using RIPPLE_SIGNING_KEY or falling back to your APP_KEY. On every request the signature is checked before anything is hydrated, and a request with a missing or wrong signature is rejected. That is the default (strict), and in production Ripple throws an error if no signing key is configured, instead of quietly falling back to a development key.

Two attributes give you finer control. #[Locked] on a property means the client can never change it, which is what you want for an order ID or a user ID that the server assigned. #[Computed] on a property makes it available to the view but keeps it out of the state that goes to the browser entirely.

One honest note: the state is signed, but it is not encrypted. The browser can read it, it just can't change it. So don't keep secrets in public properties. Use #[Computed] for anything the user shouldn't see.

What is in the first release

Once you have the basics, the rest is there already:

Directives for the things you do on every page: ripple:call, ripple:bind (with .live and .debounce.300 modifiers), ripple:loading, ripple:confirm, ripple:poll, and ripple:navigate for soft page navigation.
Lifecycle hooks: mount(), updating(), updated(), dehydrate().
Validation with Doppar's own rules. Errors come back in the same round trip and appear in $errors in your view.
Events between components with #[On] and dispatch(), plus browser events, so sibling components on a page can react to each other in the same request.
Query string sync with #[QueryString], so filters survive a refresh.
Pagination with a HasPagination trait.
Lazy loading with #[Lazy]. Heavy components show a placeholder first and load when they are needed.
File uploads with temporary storage, previews, and a cleanup command.
Full-page components with Route::ripple(), plus #[Layout] and #[Title].
A generator: php pool make:ripple Counter.
A testing API, which I want to spend a second on.

Ripple::test(Counter::class)
    ->assertSet('count', 0)
    ->call('increment')
    ->assertSet('count', 1)
    ->assertSee('Count: 1');

Ripple::test() mounts the component and sends real update payloads through the same path the browser uses, including the signed state. You get a fluent assertion API for properties, rendered HTML, validation errors, redirects, and events. Ripple's own package has over a hundred tests, and I want yours to be that easy to write.

Why it needed 4.0

Ripple requires PHP 8.5 and Doppar 4.x, and this is a good example of why the changes in this release were worth making. Ripple has its own router that adds Route::ripple(), and it swaps that router in when the package registers. It can only do that cleanly because in 4.0 the router depends on a gateway interface instead of inheriting from your app's Kernel. It installs as a launcher. Its files live in the new layout. In 3.x this would have been a fragile hack. In 4.x it is a normal package.

That is what I mean when I say 4.0 is a foundation. The launcher, gateway, and layout work in this release is what lets the first-party packages sit on top of the framework properly, and Ripple is the first one that really shows it.

Installation will be this short:

composer require doppar/ripple

Register Doppar\Ripple\RippleLauncher in your launchers array, add Ripple::scripts() to your layout, and run php pool make:ripple Counter. The full documentation ships with the package.

It is a first release, so there will be rough edges, and I'd rather hear about them from you early than late. Next week, try it and tell us what breaks.

Doppar 4.0 is the release where the framework stops borrowing a name for everything and starts using its own. I hope you like it as much as I enjoyed building it.

Try it, break it, and tell me what you think.

Documentation: doppar.com/versions/4.x/installation
Release notes and upgrade guide: doppar.com/versions/4.x/releases
Source: github.com/doppar/framework