DEV Community: Takeshi Yu

Composer Linker: The npm link for PHP Developers

Takeshi Yu — Mon, 24 Mar 2025 08:06:45 +0000

Originally published at Takeshi Yu's Blog ( https://ywh.sh/posts/composer-linker )

In modern PHP application development, particularly with the rise of microservices architecture and modular design principles, breaking down large applications into independent packages has become a best practice. This approach not only enhances code maintainability and reusability but also allows team members to focus on specific functional areas.

However, when you start managing multiple interdependent packages, the development workflow can become complex and cumbersome. This article shares how I transformed a real development pain point into a Composer plugin that simplifies the PHP multi-package development experience.

TL;DR

A Composer plugin Composer Linker that mimics npm link functionality
Solves the problem of constantly editing composer.json when developing local packages
Uses symbolic links to connect project vendor directories with local package code
No need to modify project files, avoiding accidental Git commits of development configurations
Install it globally: composer global require takeshiyu/composer-linker
Simple commands: composer link in package dir, composer link vendor/package in project dir
View linked packages with composer linked (current project), composer linked --global (all registered), or composer linked --all (all projects)

While developing Laravel projects, I frequently split core logic into separate packages to improve code reusability and project organization. However, this approach quickly introduced a challenging problem:

{
    "repositories": [
        {
            "type": "path",
            "url": "../my-package"  // Local development path
        }
    ],
    "require": {
        "vendor/my-package": "*"
    }
}

When I already have a package installed via Composer in multiple projects, the development process becomes quite tedious. Every time I need to modify the package, I must:

Modify the composer.json in each project using that package, adding the local path repository
Run composer update to use the local version
Perform development and testing
Afterward, modify each project's composer.json again to remove the local path

What's worse, if I install new packages during development, I can't simply roll back the composer.json file, as doing so would lose information about newly installed packages. I have to manually edit the file, removing only the local path section, which is error-prone.

# Installing a new package during development
composer require some/new-package

# After package development, can't simply revert composer.json
# Must manually edit to remove repositories section while preserving new packages

I've made this mistake multiple times, accidentally committing local development configurations to Git, resulting in deployment failures and unnecessary troubleshooting. It's a frustrating cycle: modify configuration, develop, forget to revert, deployment fails, fix, develop again...

Existing Solutions and Their Limitations

The community has developed several solutions, each with its own limitations:

Using Composer Path Repository

Still requires modifying composer.json, making it easy to forget to revert changes. In multi-project environments, this process must be repeated for each project.

// composer.json
{
    "repositories": [
        {
            "type": "path",
            "url": "../my-package"
        }
    ]
}

Using Environment Variables

Complex implementation, requires additional environment settings, not intuitive. Additionally, each developer may need different environment configurations.

// composer.json
{
    "repositories": [
        {
            "type": "path",
            "url": "%ENV_PACKAGE_PATH%"
        }
    ]
}

Using Git Hooks

Creating a pre-commit hook to check and prevent committing local paths. But it needs to be set up in each project, can be bypassed, not seamless. While it prevents accidental commits, it doesn't simplify the development workflow.

#!/bin/bash
if grep -q "\"type\": \"path\"" composer.json; then
    echo "Error: Local path repository detected in composer.json"
    exit 1
fi

Inspiration: npm link's Elegant Solution

The Node.js ecosystem has an elegant solution: npm link. It works by:

Running npm link in the package directory to register it globally
Running npm link package-name in projects using the package to create a link

The key advantages of this approach are:

No need to modify package.json files
Uses file system level symbolic links
Allows real-time visibility of local package changes
Simple, intuitive commands
Packages only need to be registered once and can be used in multiple projects

I realized that having a similar solution would make the development process much smoother, especially in multi-project environments.

Building Composer Linker: An Elegant PHP Package Linking Tool

After research and development, I created Composer Linker, a Composer plugin that mimics npm link functionality.

Key design principles:

No project file modifications: All configurations are stored in a global directory
Simple command interface: Usage similar to npm link
File system level operations: Using symbolic links instead of configuration changes
Global registration mechanism: Register once, use in multiple projects

First, install the plugin:

composer global require takeshiyu/composer-linker

# In the package directory
cd ~/dev/my-package
composer link

Use the local package in a project:

# In the project directory
cd ~/dev/my-project
composer link vendor/my-package

And all link information is centralized in a single JSON file:

{
    "registered_packages": {
        "foo/hello": {
            "path": "/Users/foo/dev/work/hello",
            "autoload": {
                "psr-4": {
                    "Foo\\Hello\\": "src/"
                }
            },
            "time": 1742655618
        }
    },
    "projects": {
        "/Users/foo/dev/work/demo": {
            "linked_packages": {
                "foo/hello": "/Users/foo/dev/work/hello"
            }
        }
    }
}

View link status:

# View links in the current project
composer linked

# View globally registered packages
composer linked --global

# View links in all projects
composer linked --all

Unlink a package:

composer unlink vendor/my-package

Real-World Use Cases

Composer Linker simplifies development workflows in several common scenarios:

1. Multi-Project Shared Core Package

With a core business logic package used by multiple microservices, you can register it once and link it everywhere. All projects immediately see your changes without configuration modifications.

2. Local Development and Testing

When developing new features, you can:

Work in the package directory
Link it to your test project with a simple command
See changes in real-time and iterate quickly
When finished, simply unlink without touching configuration files

3. Team Collaboration

Different team members can develop different packages simultaneously without configuration conflicts or accidental commits of local development settings.

Future Improvements

Looking ahead, I plan to enhance Composer Linker by drawing further inspiration from npm link's comprehensive features while adding more developer-friendly capabilities tailored specifically for PHP ecosystem needs.

Conclusion

Composer Linker solves a practical problem I faced in daily PHP development. While it was created to address a personal workflow issue, I believe it will be helpful to other developers facing similar challenges.

This tool brings a long-missing functionality to the PHP ecosystem, making multi-package development smoother and more seamless. Most importantly, it eliminates the worry about accidentally committing local development configurations.

If you've faced similar challenges, I invite you to try Composer Linker — it may become a valuable tool in your PHP development toolkit. The plugin is available on GitHub and can be installed directly via Composer: composer global require takeshiyu/composer-linker.

Handling Decimal Calculations in PHP 8.4: Integrating BCMath Object API with Laravel

Takeshi Yu — Thu, 23 Jan 2025 02:03:45 +0000

Originally published at Takeshi Yu's Blog ( https://ywh.sh/posts/bcmath-object-api-in-php-84 )

When developing enterprise applications, particularly those handling financial transactions, accounting systems, or inventory management, precise numerical calculations are non-negotiable. A small rounding error could lead to significant discrepancies and debugging nightmares. Let's dive into how PHP 8.4's new BCMath Object API makes handling these calculations both precise and elegant.

If you've been working with PHP for a while, you've probably encountered this classic floating-point precision issue:

$a = 0.1;
$b = 0.2;
var_dump($a + $b);  // Outputs: 0.30000000000000004

This kind of imprecision is unacceptable in financial calculations. It's not just about aesthetics – these small errors can compound and lead to real-world discrepancies in your applications.

The Foundation: Database Structure

The first step in handling precise decimal calculations starts at the database level. Using the DECIMAL type is crucial:

// In Laravel Migration
Schema::create('items', function (Blueprint $table) {
    $table->id();
    $table->decimal('quantity', 10, 3);  // Total length 10, 3 decimal places
    $table->decimal('price', 10, 3);     // Total length 10, 3 decimal places
    $table->decimal('discount', 10, 3);  // Total length 10, 3 decimal places
    $table->decimal('tax', 10, 3);       // Total length 10, 3 decimal places
    // other columns ...
});

The DECIMAL type ensures:

Exact decimal point precision
Configurable scale and precision
Suitable for financial calculations

While DECIMAL might be slightly slower than FLOAT, the trade-off for precision is well worth it in business-critical applications.

Laravel's Decimal Casting

If you're using Laravel, you can leverage its casting system to handle decimal values:

class Item extends Model
{
    protected function casts(): array
    {
        return [
            'quantity' => 'decimal:3',
            'price' => 'decimal:3',
            'discount' => 'decimal:3',
            'tax' => 'decimal:3',
        ];
    }
}

However, it's important to understand that Laravel's casting primarily handles:

Data formatting
Consistent value representation

The Hidden Type Conversion Trap

Even with proper database types and Laravel casting, you can still run into precision issues when performing calculations:

// Values from database
$item1 = Item::find(1);  // price: "99.99"
$item2 = Item::find(2);  // price: "149.99"

// Calculation without BCMath
$subtotal = $item1->price + $item2->price;
$tax = $subtotal * 0.05;  // 5% tax

var_dump($tax);  // Outputs: float(12.499000000000002) instead of 12.499

This behavior occurs because PHP automatically converts strings to numbers when you perform arithmetic operations:

// String values from database
$price1 = "99.99";
$price2 = "149.99";
echo gettype($price1);  // string

// PHP automatically converts to float during arithmetic
$total = $price1 + $price2;
echo gettype($total);   // double (float)

BCMath Before PHP 8.4: Precise But Verbose

The solution uses PHP's BCMath extension:

// Database values
$item1 = Item::find(1);  // price: "99.99"
$item2 = Item::find(2);  // price: "149.99"

// Using BCMath functions
$subtotal = bcadd($item1->price, $item2->price, 3);
$tax = bcmul($subtotal, $item2->tax, 3);

var_dump($tax);  // Precisely outputs: string(5) "12.499"

However, when calculations become more complex, the code becomes harder to read and maintain:

// Complex order calculation
$subtotal = bcmul($item1->price, $item1->quantity, 3);  // Calculate quantity
$discount = bcmul($subtotal, $item1->discount, 3);      // 10% discount
$afterDiscount = bcsub($subtotal, $discount, 3);        // Apply discount
$tax = bcmul($afterDiscount, $item1->tax, 3);           // Add 5% tax
$total = bcadd($afterDiscount, $tax, 3);                // Final amount

PHP 8.4's BCMath Object API

PHP 8.4 introduces a new object-oriented API for BCMath, making precise calculations both elegant and intuitive. When using BCMath\Number, values must be passed as strings to maintain precision - any float values will be converted to integers, leading to precision loss:

$num = new Number(3.5);    // Output: "3"
$num = new Number('4.1');  // Output: "4.1"

This is why we properly configure our database columns as DECIMAL and ensure proper PHP PDO settings or explicit casting - to maintain string representation of decimal values. Here's how we use the new API to perform precise calculations:

use BCMath\Number;

$item1 = Item::find(1);
$price = new Number($item1->price);            // price: "99.99"
$quantity = new Number($item1->quantity);      // quantity: "2"
$discountRate = new Number($item1->discount);  // 10% discount
$taxRate = new Number($item1->tax);            // 5% tax

// Calculations become natural and readable
$subtotal = $price * $quantity;
$discount = $subtotal * $discountRate;
$afterDiscount = $subtotal - $discount;
$tax = $afterDiscount * $taxRate;
$total = $afterDiscount + $tax;

var_dump($total);  // Automatically converts to string

Key benefits of the new API:

Intuitive object-oriented interface
Support for standard mathematical operators
Immutable objects ensuring value safety
Implementation of the Stringable interface

Elegant Integration with Laravel

We can make this even more elegant using Laravel's accessor pattern:

use BCMath\Number;

class Item extends Model
{
    protected function quantity(): Attribute
    {
        return Attribute::make(
            get: fn (string $value) => new Number($value),
        );
    }

    protected function price(): Attribute
    {
        return Attribute::make(
            get: fn (string $value) => new Number($value),
        );
    }

    protected function discount(): Attribute
    {
        return Attribute::make(
            get: fn (string $value) => new Number($value),
        );
    }

    protected function tax(): Attribute
    {
        return Attribute::make(
            get: fn (string $value) => new Number($value),
        );
    }
}

Or with a custom cast:

use BCMath\Number;

class DecimalCast implements CastsAttributes
{
    public function get(Model $model, string $key, mixed $value, array $attributes): mixed
    {
        return new Number($value);
    }

    public function set(Model $model, string $key, mixed $value, array $attributes): mixed
    {
        if ($value instanceof Number) {
            return (string) $value;
        }
        return (string) new Number($value);
    }
}

class Item extends Model
{
    protected function casts(): array
    {
        return [
            'quantity' => DecimalCast::class,
            'price' => DecimalCast::class,
            'discount' => DecimalCast::class,
            'tax' => DecimalCast::class,
        ];
    }
}

Then:

$item1 = Item::find(1);

$subtotal = $item1->price * $item1->quantity;
$discount = $subtotal * $item1->discount;
$afterDiscount = $subtotal - $discount;
$tax = $afterDiscount * $item1->tax;
$total = $afterDiscount + $tax;

Conclusion

In my work developing healthcare inventory systems, precise decimal calculations are crucial. Whether it's converting medication units or calculating exact costs, even small rounding errors could have serious implications. PHP 8.4's BCMath Object API, combined with Laravel's elegant model layer, has transformed how we handle these critical calculations.

This integration brings multiple benefits:

The precision we require for medical calculations
Improved code readability through object-oriented syntax
Better maintainability with Laravel's elegant abstraction
Type safety through PHP's static typing

While the traditional BCMath functions served us well for many years, this new approach significantly improves our daily development work.

That Time Composer's Timeout Drove Me Nuts

Takeshi Yu — Mon, 30 Sep 2024 00:00:00 +0000

Originally published at Takeshi Yu's Blog (https://ywh.sh/posts/composer-process-timeout)

You know what's frustrating? Spending hours debugging what seems like a simple Docker build issue, only to find out it's something completely unexpected. That's exactly what happened to me recently while working on a Laravel deployment.

Pretty standard stuff - I was building a Docker image for a Laravel app that needed to run on Linode. Nothing fancy, just your typical setup:

PHP8.3 with all the usual suspects.
Setting up MongoDB drivers and extensions via PECL.
Installing Caddy Server.
Supervisor to keep processes in check.
Copying files and configuring related services.

The Problem

Everything seemed fine until the build kept failing at exactly 300 seconds. Like clockwork. Here's what I was seeing:

=> CANCELED exporting to image                                                                                       37.6s
...
The following exception is caused by a process timeout
Check https://getcomposer.org/doc/06-config.md#process-timeout for details

ERROR: failed to solve: Canceled: context canceled
In Process.php line 1205:

  The process "DOCKER_BUILDKIT=1 docker 'build' '--no-cache' '-t' 'my/api' '.'" exceeded the timeout of 300 seconds.

build [--dev] [--no-dev] [--] [<args>...]

The Head-Scratching Begins

My first thought? "Oh great, Docker's being Docker again." You know how it goes - you immediately blame the most obvious suspect. I spent a good chunk of time diving into Docker's documentation, looking for some mysterious build timeout setting that I must have missed. But something didn't add up. Many official images take way longer than 300 seconds to build, and they work just fine. Plus, if Docker had a built-in timeout, wouldn't it be, I don't know, documented somewhere?

The Plot Thickens

Being a good developer (or at least trying to be), I figured I'd try to optimize my build with multi-stage builds. Here's what I came up with:

FROM php:8.3-fpm AS mongodb-builder

RUN apt-get update && apt-get install -y \
    libssl-dev \
    && pecl install mongodb \
    && docker-php-ext-enable mongodb

# ...

FROM php:8.3-fpm

COPY --from=mongodb-builder /usr/local/lib/php/extensions /usr/local/lib/php/extensions
COPY --from=mongodb-builder /usr/local/etc/php/conf.d/docker-php-ext-mongodb.ini /usr/local/etc/php/conf.d/

RUN apt-get update && apt-get install -y \
        curl gnupg gosu zip unzip git supervisor sqlite3 libcap2-bin \
        libpng-dev dnsutils librsvg2-bin fswatch vim libzip-dev \
        libxml2-dev libcurl4-openssl-dev libssl-dev \
    && docker-php-ext-install zip pdo_mysql bcmath soap intl opcache \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# ...

Did it fix the problem? Nope. But it did make my Dockerfile look prettier, so there's that.

The Lightbulb Moment

Then I noticed something in the error message that I'd glossed over before:

Check https://getcomposer.org/doc/06-config.md#process-timeout for details

Composer? But I'm just installing Composer in my Dockerfile:

&& curl -sLS https://getcomposer.org/installer | php -- --install-dir=/usr/bin/ --filename=composer \

That's when it hit me. I had these neat little shortcuts in my composer.json:

"lint": "pint",
"clear": [
    "@php artisan lighthouse:clear-cache",
    "@php artisan config:clear",
    "@php artisan route:clear",
    "@php artisan view:clear",
    "@php artisan cache:clear"
],
"test": [
    "@lint",
    "@clear",
    "pest --profile --colors=always"
],
"docker": "DOCKER_BUILDKIT=1 docker",
"build": [
    "@clear",
    "@docker build --no-cache -t tgk/be .",
    "@docker tag tgk/be heytakeshi/tgk-be:latest",
    "@docker push heytakeshi/tgk-be"
]

And I was running my Docker builds through Composer with composer build. Guess what has a 300-second default timeout? Yep, Composer.

The Fix

The solution was embarrassingly simple. Either:

Tell Composer to chill out a bit ( managing the process timeout ):

"config": {
    // ...
    "process-timeout": 600
},

Or move the Docker commands to a shell script where Composer can't boss them around:

#!/bin/bash

DOCKER_BUILDKIT=1 docker build --no-cache -t my/api .
docker tag my/api my/api
docker push my/api

I went with option 1 because I was too lazy to update all my deployment scripts.

The Lesson

Sometimes the problem isn't where you think it is. I spent way too long looking at Docker documentation when the answer was right there in the error message. Also, maybe running everything through Composer scripts isn't always the best idea - but that's a problem for future me.

Next time you hit a weird timeout, check your Composer config. It might just save you a few hours of Docker documentation diving.