DEV Community: Yonel Ceruto

It's nice to hear that my free-time open-source work has been useful for others building real applications. Feedback like this makes the effort worthwhile.

Yonel Ceruto — Mon, 23 Mar 2026 14:54:01 +0000

Matt Mochalkin

Jan 2

Mastering Multi-Step Forms in Symfony 7.4

#symfony #php #productivity #programming

Comments 2

9 min read

When “Just Calling a Function” Isn’t That Simple Anymore

Yonel Ceruto — Thu, 26 Feb 2026 08:51:58 +0000

At some point in almost every project, something small starts to feel heavier than it should.

You begin with a clean controller that delegates to a handler, then you add validation, then logging. Maybe a transaction. Then consistent error mapping. Nothing dramatic, just normal application growth.

A few months later, calling a handler isn’t just “calling a handler” anymore.

Some controllers validate first, others rely on the handler. Some catch domain exceptions and map them to HTTP responses. Others let them bubble up. Background workers behave slightly differently. CLI commands do their own thing.

The business logic is fine. The execution semantics aren’t.

And that’s when it becomes clear: invoking a callable is not just a method call. It’s an execution boundary.

That realization led to CallableInvoker.

Invokable objects have become common in modern PHP, from single-action controllers to DDD-style handlers using __invoke.

After using them extensively, I noticed something subtle: they simplify composition, but they also expose inconsistencies in how we execute application logic.

A War Story: The Job That Behaved Differently

In a previous project, we had an invokable service that generated invoices. It was used both by an HTTP endpoint and by a nightly background job.

A few weeks after release, finance noticed that invoices generated overnight didn’t match the ones created manually in the admin panel. The differences were small, mostly rounding, but real.

After tracing it, we found the cause: the HTTP flow always had an authenticated user, which carried tenant and currency configuration. The scheduled job didn’t. It fell back to defaults.

The service wasn’t wrong.

The way we prepared and executed it was inconsistent depending on where it was called from.

That’s when it became clear the problem wasn’t the business logic, it was the lack of a single, predictable way to invoke it.

A Better Way to Execute Callables

In PHP, calling a callable is trivial:

($handler)($command);

But real applications are not trivial.

What if:

the callable has multiple parameters with defaults?
some arguments should come from a runtime contextual data?
you want consistent logging or transactions around execution?
retries or metrics should apply everywhere?

CallableInvoker reframes the problem.

Instead of asking, “How do I call this?”, it asks:

How should this be executed, and under what context?

It uses reflection to inspect the callable’s signature, resolves arguments from a provided context, applies defaults, and executes the callable through a pipeline.

That pipeline can include decorators, small wrappers that add behavior around execution.

Not inside your business logic. Around it.

From Boilerplate to Focused Handlers

Consider a simple handler:

class HelloHandler
{
    public function __invoke(string $name, int $age = 23): string
    {
        return "Hello, $name! You are $age years old.";
    }
}

$handler = new HelloHandler();

Instead of manually extracting arguments and orchestrating execution:

use OpenSolid\CallableInvoker\CallableInvoker;

$invoker = new CallableInvoker();

$result = $invoker->invoke(
    callable: $handler,
    context: ['name' => 'Evelyn']
);

echo $result; // Output: Hello, Evelyn! You are 23 years old.

Behind the scenes:

The invoker inspects the signature.
It resolves parameters from context.
It applies defaults.
It executes the callable through registered decorators (if any).

The handler stays focused on business rules. Everything else becomes execution policy.

Decorations: Infrastructure Without Pollution

Decorators are where this becomes useful.

A decorator can:

run logic before execution,
wrap the callable in a transaction,
measure execution time,
translate exceptions,
or modify the result.

Instead of scattering logging, or transaction boundaries across controllers and workers, you define them once.

Now every invocation follows the same rules. And that consistency is what we were missing in that earlier project.

In practice, decorators and parameter value resolvers don’t have to be global. They can be grouped and prioritized for specific artifact types. For example, HTTP controllers might have a different decorator stack than message handlers or CLI commands.

You can define execution profiles where certain behaviors apply only to a subset of callables, and control their order explicitly.

That means you’re not just centralizing execution, you’re shaping it per context.

Symfony Integration (Optional, But Powerful)

Although CallableInvoker is framework-agnostic, it integrates naturally with Symfony.

Symfony already resolves controller arguments, supports invokable console commands, and wires message handlers through Messenger. CallableInvoker can plug into that ecosystem by being registered as a service and configured with autowired decorators and value resolvers.

In practice, this means:

You can inject CallableInvoker anywhere in your application.
Decorators and resolvers can be tagged and auto-registered.
The Symfony container can participate in argument resolution.
Different execution profiles can be configured per environment or entry point.

This allows you to extend Symfony’s argument resolution and execution wrapping beyond controllers and commands, bringing the same behavior into your application layer.

It’s Not Magic (And It’s Not Free)

A note on tradeoffs: this approach adds indirection.

Reflection has overhead (usually negligible, but real).
There’s a mental model to understand.
Debugging execution flow requires knowing the decorator chain.

This isn’t something I’d use in a throwaway script or a small CRUD app.

But in long-lived systems, especially those mixing HTTP, CLI, and asynchronous handlers, having a single execution abstraction pays off quickly.

Why This Matters in Real Systems

As applications evolve, divergence happens quietly.

When callables don’t share a strict interface, when __invoke signatures vary, arguments aren’t known at compile time, or inputs depend on the entry point, invocation becomes a dynamic resolution problem, not just a method call.

CallableInvoker centralizes how callables are prepared and executed. Even when their shape varies, their behavior stays consistent.

And that consistency is architectural leverage.

A Small Tool That Changes the Shape of Your Code

The biggest improvements in a system often come from refining repeated patterns.

Calling a callable is one of those patterns.

Turning that from “just a function call” into a controlled execution boundary doesn’t add features. It adds discipline.

In our case, it eliminated duplicated glue code, aligned error handling across entry points, and made new handlers simpler to write.

It didn’t make the system flashy. It made it consistent.

And for long-lived applications, consistency is what scales.

Take a tiny detour to 👉 https://github.com/open-solid/callable-invoker

If it makes your inner developer smile even a little... tap that ⭐ and make the repo’s day! 😄

Generic DBAL Types for Similar Value Objects

Yonel Ceruto — Fri, 26 Dec 2025 02:51:34 +0000

If you use Value Objects as entity identifiers in PHP, you eventually drown in custom DBAL types: boilerplate classes, repetitive configuration, and fragile mappings that break silently when someone forgets to register a type or the type name changes.

This problem shows up consistently in projects built with Symfony and Doctrine, especially when following DDD-style modeling where identifiers are not raw UUIDs but explicit Value Objects.

use Symfony\Component\Uid\UuidV7;

abstract class Uid
{
    public static function create(): static
    {
        return new static(UuidV7::generate());
    }

    public static function fromString(string $value): static
    {
        return new static(new UuidV7($value)->toRfc4122());
    }

    final private function __construct(
        private(set) string $value,
    ) {
    }
}

class ProductId extends Uid
{
    public function equals(self $other): bool
    {
        return $this->value === $other->value;
    }
}

This post explains how to implement a single generic DBAL type that supports these ID Value Objects.

This is not a primer on Value Objects or Doctrine internals. It assumes prior familiarity with both and focuses strictly on eliminating manual work and improving the DX. For that reason, all code examples are intentionally shortened to emphasize the core ideas.

Now let’s continue and create an entity identified by a first-class Value Object, not a scalar:

use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class Product
{
    #[ORM\Id, ORM\Column]
    private(set) ProductId $id;
}

That definition is clean, intentional, and fully valid at the domain level. The failure appears only when the ORM tries to bridge the gap to persistence.

At runtime, Doctrine halts with the following error:

[FAIL] The entity-class App\Entity\Product mapping is invalid:
 * The field 'App\Entity\Product#id' has the property type 'App\Entity\ProductId' that differs from the metadata field type 'string' returned by the 'string' DBAL type.

💥 Doctrine has no notion of ProductId as a domain concept. It sees a PHP class on one side and a scalar database column on the other, and it refuses to guess how the two relate.

#[ORM\Id, ORM\Column(type: ProductId::class)]
private(set) ProductId $id;

The immediate fix is to make the mapping explicit so Doctrine no longer has to guess. By providing ProductId::class, you are effectively telling DBAL: “there exists a column type with this name”, DBAL then looks it up in its internal type registry.

Usually you would set a symbolic DBAL type name here (e.g. ORM\Column(type: 'product_id')). In this case, we're using the Fully-Qualified Class Name (FQCN) of the concrete ID class instead. This is intentional, and the reason will become clear later.

Unknown column type "App\Entity\ProductId" requested. Any Doctrine type that you use has to be registered with \Doctrine\DBAL\Types\Type::addType(). You can get a list of all the known types with \Doctrine\DBAL\Types\Type::getTypesMap(). If this error occurs during database introspection then you might have forgotten to register all database types for a Doctrine Type. Use AbstractPlatform#registerDoctrineTypeMapping() or have your custom types implement Type#getMappedDatabaseTypes(). If the type name is empty you might have a problem with the cache or forgot some mapping information.

💥 It still fails because no such type has been registered. So let’s address the problem by introducing a dedicated DBAL type for these ID value objects.

First, create a new DBAL type class extending the abstract Type:

class UidType extends Type
{
    public function getSQLDeclaration(array $column, AbstractPlatform $platform): string
    {
        return $platform->getGuidTypeDeclarationSQL($column);
    }

    public function convertToPHPValue(mixed $value, AbstractPlatform $platform): ?Uid
    {
        $class = $this->getUidClass();

        // other checks ...

        return $class::fromString($value);
    }

    public function convertToDatabaseValue($value, AbstractPlatform $platform): ?string
    {
        $class = $this->getUidClass();

        if ($value instanceof $class) {
            return $value->value;
        }

        // other checks ...
    }

    /**
     * @return class-string<Uid>
     */
    private function getUidClass(): string
    {
        return self::lookupName($this);
    }
}

Then, register this new DBAL type for the missing column type:

doctrine:
    dbal:
        types:
            App\Entity\ProductId: App\DBAL\Type\UidType

This class defines a single generic DBAL type able to convert all the values back and forth from multiple identifier Value Objects that all extend a common Uid base class.

At the DBAL level, it behaves like any other custom type:

getSQLDeclaration() delegates column definition to the platform, using a GUID-compatible storage
convertToPHPValue() transforms the database scalar into a domain identifier
convertToDatabaseValue() extracts the scalar value from the identifier before persistence

So far, nothing unusual. The critical part is how the concrete identifier class is resolved:

/**
 * @return class-string<Uid>
 */
private function getUidClass(): string
{
    return self::lookupName($this);
}

Type::lookupName($this) returns the registered DBAL type name for the current instance. In this design, that name is not a symbolic alias like product_id. It is the FQCN of the identifier itself (App\Entity\ProductId).

Because the column mapping uses type ProductId::class, and the DBAL configuration registers that same FQCN as a type pointing to UidType, the DBAL type name is the identifier class.

As a result, the DBAL type instance knows which identifier it represents. getUidClass() returns the exact concrete Uid subclass to instantiate, and no subclassing, no switch statements, no per-ID DBAL types.

Looking to simplify this further?

DBAL type registration can be automated, and the ORM\Column::$type value can be inferred directly from the property type, eliminating repetitive configuration and manual wiring.

This solution for generic DBAL types can also be applied to any kind of Value Objects where persistence follows a consistent mapping rule and the concrete class can be resolved at runtime from the DBAL type name.

This is my last post of the year. Happy holidays!

PHP Callable Decorators

Yonel Ceruto — Fri, 20 Sep 2024 03:50:58 +0000

In this post, we're diving into the fascinating world of callable decorators—an advanced technique that can add a new layer of functionality to your functions or methods. Callable decorators can transform the way you think about code organization and reuse.

So, grab your favorite beverage, and let’s unlock the potential of PHP decorators together!

Disclaimer (Click here)

This article presents a personal workaround for PHP decorators, as PHP doesn't natively support them. The implementation is based on my custom code and practices, not an official PHP feature.

Before you continue, please review these prerequisites if you're not familiar with them:

Are you ready? let's start with the following example:

namespace Banking\Account;

class TransferAccountFunds
{
    public function execute(Account $sender, Account $receiver, Money $amount): void
    {
        // Check if balance is sufficient; throw an exception otherwise
        // Decrease balance with given amount
        // Add transaction record for debit operation
        $sender->debit($amount);

        // Increase balance with given amount
        // Add transaction record for credit operation
        $receiver->credit($amount);
    }
}

Consider this service class that transfers funds between bank accounts. This operation involves multiple database changes, so it must be wrapped in a single atomic transaction to ensure all data is either fully saved or none at all if an exception occurs.

A feasible approach is to inject your database connection service, wrap your code explicitly in a try/catch block, and manually handle the "start transaction," "commit," and "rollback" statements.

class TransferAccountFunds
{
    public function __construct(private DatabaseConnection $conn) 
    {
    }

    public function execute(Account $sender, Account $receiver, Money $amount): void
    {
        $this->conn->startTransaction();
        try {
            $sender->debit($amount);
            $receiver->credit($amount);

            $this->conn->commit();
        } catch (Exception $e) {
            $this->conn->rollback();
            throw $e;
        }
    }
}

This method works but mixes persistence concerns with your business logic, complicating your code. Plus, you’d need to repeat it for every similar use case, reducing maintainability.

So, how can we accomplish this without modifying our business logic? 🥁

Callable Decorator to the Rescue!!

Since PHP 8, #[attributes] let you add structured metadata to code elements like methods, which can be inspected at runtime. They act as an embedded configuration language, decoupling the generic implementation of a feature from its concrete use.

Combining attributes with the decorator pattern lets us elegantly manage the transactional requirement. But first, let’s dive into what a callable decorator is.

A "Callable Decorator" adds new behaviors to a callable by wrapping it in another callable that includes the additional behaviors. It’s a simple concept, but it can be a bit tricky to grasp. Let’s break down how to create one.

function decorate(callable $func): callable
{
    return function (mixed ...$args) use ($func): mixed {
        // do something before

        $result = $func(...$args);

        // do something after

        return $result;
    };
}

A callable decorator takes a callable as an argument, wraps it in a new function (the “wrapping phase”), and then adds additional functionality before or after the function call (the “enhancement and call phase”).

By returning a callable, this approach requires executing the decoration first and then calling the decorated function as if it were the original.

$func = function (int $x): void {
    echo $x;
};
$func = decorate($func); // decoration phase
$func(x: 0); // enhancement and calling phase.

Want to give it a try? Check this out: https://3v4l.org/bbNql

Callable Decorators are especially useful in situations where you want to:

Decouple functionality from its actual usage without using a interface to achieve it.
Perform an action before or after a function call (e.g. logging, security checks, validation).
Conditionally skip the function call by returning early (e.g. caching).
Modify the function’s result (e.g. serialization, normalization, formatting).

Unlike traditional "Object Decorators", Callable Decorators focus on functions and methods only, making them ideal for modifying specific behaviors without altering the entire object.

This technique consists of two main elements:

The decorator attribute: Holds all metadata and links a callable to its decorator.
The decorator itself: Takes a callable as an argument and returns another callable with additional functionality.

Shall we create our transactional decorator using this approach? Let’s do it!

#[Attribute(Attribute::TARGET_METHOD)]
class Transactional
{
    public function decoratedBy(): string
    {
        return TransactionalDecorator::class;
    }
}

class TransactionalDecorator
{
    public function __construct(private DatabaseConnection $conn)
    {
    }

    public function decorate(callable $func): callable
    {
        return function (mixed ...$args) use ($func): mixed {
            $this->conn->startTransaction();
            try {
                $result = $func(...$args);
                $this->conn->commit();
                return $result;
            } catch (Exception $e) {
                $this->conn->rollback();
                throw $e;
            }
        };
    }
}

So far, we’ve built a generic decorator that can wrap any callable in a transactional database operation, no matter its origin. Next, we’ll use the #[Transactional] attribute to specify which callable should be wrapped.

Let’s decorate our initial example:

class TransferAccountFunds
{
    #[Transactional]
    public function execute(Account $sender, Account $receiver, Money $amount): void
    {
        $sender->debit($amount);
        $receiver->credit($amount);
    }
}

Is that all? Not quite. We’re missing the step where the attribute is read at runtime and the linked decorator is applied to ensure the TransferAccountFunds::execute() method is correctly wrapped before it’s called.

The proper implementation of this step will be covered in the next article of this series, where we’ll see how to apply callable decorators to enhance your code’s functionality, providing a flexible way to manage cross-cutting concerns.

Stay tuned!

Because I love the Symfony framework, I’m introducing this approach for Symfony Controllers through a new Decorator component. However, you can find this integration already available in two PHP libraries: yceruto/decorator and yceruto/decorator-bundle (compatible with Symfony 6.4 or superior).

Bundling Your Symfony UX Twig Components

Yonel Ceruto — Mon, 29 Jul 2024 06:52:05 +0000

Have you heard about Symfony UX Twig Components? If not, I recommend starting by reading the official documentation to get firsthand understanding. However, in this article, I will give a brief introduction and then quickly jump to today's main topic: How to bundle Twig Components for reuse in your applications.

Symfony UX components are divided into two main categories: those consisting of a PHP class (controller) plus a Twig template (user interface) plus optional assets (JavaScript, CSS, etc.), which I will call "FullStack Components" in this article; and those made up solely of a user interface (Twig template and assets), referred to as "UI-only Components," also known as "Anonymous Twig Components."

FullStack components, thanks to their controller (the PHP class), can fetch information from a data source and render it on the user interface (the Twig template), making them incredibly dynamic tools. Think of them as compact, reusable controllers, each with a specific responsibility and UI. For example, a table of recommended products could be displayed both on your site's homepage and on individual product pages.

In contrast, the UI-only Components don't have a controller (the PHP class) and are useful when you need to reuse a user interface whose content is static or comes from an unknown data source. For example, a button with a label property or an alert message.

There are also other subcategories of UX components, such as "Live Components," and components whose UI is not rendered using a Twig template but is instead generated at runtime using pure PHP like UX Icon component. I won’t delve deeper into these components here, but you can find more information in the Symfony UX documentation.

Now let's get to the meat of the matter.

Bundling FullStack Components

Following the default recipe configuration, the twig_component extension includes a defaults config. This allows us (the bundles) to prepend new namespaces/paths and register our own FullStack components.

Here is an example of the structure you could follow to achieve this:

acme-bundle/
├── assets/
│   ├── dist/
│   │   ├── controller.js
│   │   └── style.min.css
│   └── package.json
├── src/
│   └── Twig/
│       └── Component/
│           └── Search.php
└── templates/
    └── components/
        └── Search.html.twig

The components/ directory is not mandatory for FullStack components; they can be placed at the root of the templates if your bundle focuses solely on UX components. However, it’s necessary for UI-only components. Therefore, I’ve placed both types under the same directory for consistency.

Here is the configuration you need to add to make the FullStack component work:

class AcmeBundle extends AbstractBundle
{
    public function prependExtension(ContainerConfigurator $container, ContainerBuilder $builder): void
    {
        $builder->prependExtensionConfig('twig_component', [
            'defaults' => [
                'AcmeBundle\Twig\Component\\' => [
                    'template_directory' => '@Acme/components/',
                    'name_prefix' => 'Acme',
                ],
            ],
        ]);
    }

    // ...
}

Although the term defaults in the configuration might be a bit misleading (terms like mappings or namespaces might be clearer), this section allows you to register your own Twig components namespace and the necessary options to locate them.

Here's a trick: the template_directory isn't actually a directory path but rather a prefix for Twig template paths. It's unclear if this is intentional, but that's how it's used in the code. By taking advantage of this, I prefixed the path with the @Acme/ namespace. It worked perfectly!

Ensure the namespace you use matches the one assigned to your bundle by the TwigBundle. You can use the debug:twig command to find this out. If there's a mismatch, Twig won’t be able to locate your component templates.

For consistency, also use this namespace for the name_prefix option. If your Search.php component controller doesn't directly specify a component name, it will default to using this prefix. For instance, the component name would be Acme:Search by default.

If your UX component requires certain assets and your application uses the AssetMapper component, the simplest approach is to prepend the asset path as well:

class AcmeBundle extends AbstractBundle
{
    public function prependExtension(ContainerConfigurator $container, ContainerBuilder $builder): void
    {
        $container->prependExtensionConfig('framework', [
            'asset_mapper' => [
                'paths' => [
                    __DIR__.'/../../assets/dist' => '@symfony/ux-acme-component',
                ],
            ],
        ]);
    }

    // ...
}

This will guarantee that your assets are imported correctly and associated with your component. And that wraps up everything about FullStack Twig Components!

From here, you can reuse your components across any application using either syntax:

<twig:Acme:Search></twig:Acme:Search>  

or  

{{ component('Acme:Search') }}

Bundling UI-only Components

Handling UI-only components is more complex because there is only one anonymous_template_directory. I believe we can improve this by allowing the registration of custom paths, similar to what we do with FullStack components. However, the term used here is misleading—it's not a directory path but a Twig template prefix. This prefix is used to concatenate and locate the template.

UI-only components follow a different convention from FullStack components, so they can't be located in the same way. Let’s look at an example to illustrate this:

<twig:Acme:Alert></twig:Acme:Alert>

Even if you store the Alert component in the <acme-bundle>/templates/components/ directory, you will encounter the following error:

Error rendering "Acme:Alert" component: Unknown component "Acme:Alert". And no matching anonymous component template was found.

The issue arises because the loading mechanism for UI-only components relies on the anonymous_template_directory configuration, which by default points to the templates/components/ directory in your application's path, not in the bundle path as you might expect. So, what can we do about this?

Behind the scenes, the component template finder service attempts to locate the template at templates/components/Acme/Alert.html.twig. Naturally, this template doesn't exist at the application location.

To address this issue, start by creating a new directory named Acme/ within the existing templates/components/ directory in your bundle. Then, place the Alert.html.twig template inside this new directory:

acme-bundle/
└── templates/
    └── components/
        ├── Acme/
        │   └── Alert.html.twig
        └── Search.html.twig

This adjustment partially resolves the issue. However, we still need to ensure that the loader searches within the bundle path. Fortunately, there is a Twig feature that can assist us with this.

In Twig, if a template name lacks a namespace, the loader will search all registered paths that don't specify a namespace. You can identify these paths by running the debug:twig command ((None) namespace).

So, how about registering unnamespaced Twig paths within your bundle's context? This trick lets Twig access the bundle's templates without needing a namespace. However, keep in mind this is more of a workaround to help the loader locate your bundle templates, specifically those under the templates/components/Acme/ directory:

final class AcmeBundle extends AbstractBundle
{
    public function prependExtension(ContainerConfigurator $container, ContainerBuilder $builder): void
    {
        // ...

        $builder->prependExtensionConfig('twig', [
            'paths' => [
                'templates/bundles/AcmeBundle/' => null,
                dirname(__DIR__).'/templates/' => null,
            ],
        ]);
    }
}

Great! Now you can render your <twig:Acme:Alert> component. Just refresh the page, and it will display the component from <acme-bundle>/templates/components/Acme/Alert.html.twig.

Overriding Your Bundled UX Components

Sometimes, your generic UX components require UI tweaks. Consider a scenario where you're using a Bootstrap or Tailwind bundle that packages common UX components. Instead of creating entirely new components, including PHP controllers, you can simply override the Twig template (UI) by following the same TwigBundle convention.

The overriding rule works on a priority basis: the first template found takes precedence. That's why we registered the path 'templates/bundles/AcmeBundle/' => null at a high position in the prepend method.

Simply place your customized templates in templates/bundles/AcmeBundle/, following the same organization as the bundle, and the Twig loader will handle the rest, ensuring your modifications are used:

your-app/
└── templates/
    └── bundles/
        └── AcmeBundle/
            └── components/
                ├── Acme/
                │   └── Alert.html.twig
                └── Search.html.twig

Remember, components are designed to be reusable. Avoid creating a UX component unless you're sure it will be used at least twice. It's always better to refactor later, extract, and create a component when there's a real need for it.

Happy hacking! Cheers!

Why OOP is Your Old New Best Friend: The Date Distance Problem

Yonel Ceruto — Sat, 13 Jul 2024 17:46:41 +0000

Calculating the distance between two dates is relatively straightforward. There are multiple ways. Think about it for a moment... If you like functional programming, your first thought might look like this:

function date_distance(string $origin, string $destination): int 
{
    return strtotime($destination) - strtotime($origin);
}

That's it! Definition and implementation. It gets the job done! Simple, right? But hold on... simple isn't always right!

Trying to reuse this function feels like using someone else's toothbrush: it might seem okay in a hurry, but you're not really sure what issues it might cause.

Developers usually read just the first few lines:

function date_distance(string $origin, string $destination): int

If that definition is self-explanatory, nobody cares about the implementation. But is it? Is the return value in seconds, milliseconds, or something else? What about the date arguments, $origin and $destination? They seem to be dates, but it's not entirely clear. Confusing, right?

Ensuring clarity on what every function does, what inputs it needs, and what it returns isn't easy. Even for you, because trust me, you'll eventually forget the details of your own code.

Wouldn't it be better to have a specific return type called Seconds? Absolutely! It's not just any random number, and that distinction matters. We want to clearly indicate that the distance will be in Seconds. Let's update the function to reflect this:

function date_distance(DateTime $origin, DateTime $destination): Seconds

So, instead of any datetime string, we ask for a DateTime object representing a valid datetime. And instead of returning just any integer, we return the number of Seconds.

class Seconds
{
    public function __construct(private int $distance) {}

    // ...
}

function date_distance(DateTime $origin, DateTime $destination): Seconds
{
    $distance = $destination->getTimestamp() - $origin->getTimestamp();

    return new Seconds($distance);
}

The implementation looks a lot like the first version, with small changes. We're using objects and methods instead of scalar values and functions! The responsibility of parsing the datetime is handled by requiring a DateTime instance. Nice! And I'm completely sure about the return type, no doubts, it's in seconds.

The Seconds object isn't just a data container; it includes behavior through methods. You can add methods for time unit conversions like toMinutes() or toDays(), and maybe an asAbsolute() method to always return a positive distance. Super!

However, there's another way to think about this solution. Read it again:

function date_distance(DateTime $origin, DateTime $destination): Seconds
{
    $distance = $destination->getTimestamp() - $origin->getTimestamp();

    return new Seconds($distance);
}

Any other improvements? Let's look at the usage snippet:

$seconds = date_distance($dateA, $dateB);

In our heads, it reads as "Compute the date distance between date A and date B in seconds," which is correct, but it could simply be "Compute the date A distance to date B in seconds." Still pondering? There's a principle that has always helped me reason about object-oriented solutions: "Tell, Don't Ask."

"Tell, Don't Ask" principle states that Object-orientation combines data with behavior (methods). Instead of requesting data from an object, we should tell the object what to do.

In this sense, we should never create a global function to solve a problem unless there is no relevant Object concept around it. So, this is what we want to achieve now:

$seconds = $dateA->distanceTo($dateB);

The distanceTo() method doesn't exist in the DateTime class, but we can extend DateTime and create our own DatePoint class:

class DatePoint extends DateTime
{
    public function distanceTo(self $destination): Seconds
    {
        $distance = $destination->getTimestamp() - $this->getTimestamp();

        return new Seconds($distance);
    }
}

Note the self $destination argument and the $this->getTimestamp() call. This approach keeps the function relevant to the DatePoint object, ensuring that the calculation of the distance between two dates is neatly encapsulated within the object-oriented design.

This way, we leverage the full power of object-oriented programming by bundling data and behavior together.

As a challenge, I invite you to develop a complete solution that covers all the issues explained here, including validation constraints around the origin and destination dates.

If you enjoyed this content, please leave a like—it motivates me to write more. Also, share your feedback if you have a different perspective or want to elaborate on this topic.

Ciao!

Symfony App Config in 2 steps

Yonel Ceruto — Wed, 22 May 2024 21:27:34 +0000

Customizing your Symfony application often involves tweaking configurations. For instance, enabling CSRF protection requires editing the framework.yaml file like this:

framework:
    csrf_protection: true

These configurations, stored in the config/packages directory, come from third-party packages known as "Bundles." Each bundle can add its own configuration, identified by an extension alias (e.g. framework) and its settings (e.g. csrf_protection: true).

But what if you want to add custom configurations for your own application? Do you need to create a bundle for that? Not at all. Let me show you how to add your own application configuration in just 2 simple steps.

Step 1: Create an Extension Class

First, create an extension class to define your configuration. This class extends the Symfony\Component\DependencyInjection\Extension\AbstractExtension class and implements the configure() method:

<?php
namespace App\Extension;

use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Extension\AbstractExtension;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

final class AppExtension extends AbstractExtension
{
    public function configure(DefinitionConfigurator $definition): void
    {
        $definition->rootNode()
            ->children()
                ->booleanNode('some_toggle')->defaultFalse()->end()
            ->end()
        ;
    }

    public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void
    {
        $container->parameters()
            ->set('app.some_toggle', $config['some_toggle'])
        ;
    }

    public function getAlias(): string
    {
        return 'app';
    }
}

Here, we've defined a configuration with a single boolean value called some_toggle (default is false). This is used later by the loadExtension() method to create a container parameter that can be injected into your services or controllers.

The getAlias() method is optional. By default, Symfony will guess the alias from the class name, so AppExtension becomes app. You only need to override it if you want to use a different extension alias, e.g. project_name instead of app.

Step 2: Register the Extension Class

Next, register this extension class in the container within your Kernel class build() method, so the container knows about it:

<?php

namespace App;

use App\Extension\AppExtension;
use Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\HttpKernel\Kernel as BaseKernel;

class Kernel extends BaseKernel
{
    use MicroKernelTrait;

    protected function build(ContainerBuilder $container): void
    {
        $container->registerExtension(new AppExtension());
    }
}

And that’s it! Now you can add your own application configuration in a new config/packages/app.yaml file:

app:
    some_toggle: true

I hope this guide helps you add custom configurations to your Symfony applications. If you have any questions, feel free to ask in the comments below.