🐥 YellowDuck.be

🐥 The MySQL null-safe equality operator: <=>

2026-06-18T17:00:00Z

If you've worked with MySQL long enough, you've probably been bitten by NULL comparisons at least once. A query that should return results returns nothing. A WHERE clause that should exclude a row doesn't. The culprit is almost always the three-valued logic of SQL — and the null-safe equality operator <=> is one of the cleanest tools for dealing with it.

The problem with `=` and `NULL`

In SQL, NULL represents the absence of a value — the unknown. Because of this, any comparison involving NULL using the standard = operator yields NULL (not TRUE or FALSE), and NULL is falsy in a WHERE clause.

SELECT NULL = NULL;   -- NULL
SELECT NULL = 1;      -- NULL
SELECT 1 = 1;         -- 1 (TRUE)

This means:

SELECT * FROM users WHERE deleted_at = NULL;  -- returns nothing

The idiomatic fix is IS NULL / IS NOT NULL, but that only works for literal null checks. The moment you're comparing two columns — one or both of which might be NULL — things get awkward fast.

-- This silently drops rows where either column is NULL
SELECT * FROM orders WHERE shipping_address = billing_address;

Enter `<=>`

MySQL's null-safe equality operator <=> behaves exactly like =, except it treats NULL as a comparable value. Two NULLs are considered equal, and a NULL compared to any non-null value is FALSE.

SELECT NULL <=> NULL;   -- 1 (TRUE)
SELECT NULL <=> 1;      -- 0 (FALSE)
SELECT 1 <=> 1;         -- 1 (TRUE)
SELECT 1 <=> 2;         -- 0 (FALSE)

This makes it safe to compare nullable columns directly:

-- Correctly includes rows where both columns are NULL
SELECT * FROM orders WHERE shipping_address <=> billing_address;

A real-world example

Consider a polymorphic subscriptions join table that maps users to subscribable entities (posts, documents, threads, etc.). The goal: return all subscribers excluding the item's author, even when author_id might be NULL.

The naive approach breaks silently:

WHERE subscriptions.user_id != posts.author_id

When author_id is NULL, this evaluates to NULL, so the row is dropped — meaning a user who subscribes to a post with no author would incorrectly disappear from the result.

The null-safe fix:

NOT (subscriptions.user_id <=> (
    SELECT author_id FROM posts WHERE id = subscriptions.item_id
))

This reads as: "keep this row unless the subscriber's user_id exactly matches the author_id, treating NULL as a concrete equal value." When author_id is NULL and user_id is not, the <=> returns FALSE, so NOT FALSE is TRUE — the row is kept. Correct behaviour in all cases.

`<=>` vs. the alternatives

Approach	Handles NULL?	Readable?	Standard SQL?
`col = val`	No	Yes	Yes
`col IS NULL`	Yes (literal only)	Yes	Yes
`COALESCE(col, '') = COALESCE(val, '')`	Yes (with sentinel)	Passable	Yes
`(col = val OR (col IS NULL AND val IS NULL))`	Yes	Verbose	Yes
`col <=> val`	Yes	Yes	No (MySQL/MariaDB)

The COALESCE sentinel approach is fragile — you need to pick a value that can never appear in real data. The verbose OR (IS NULL AND IS NULL) pattern works but is noisy. <=> wins on brevity and correctness, at the cost of portability.

When to use it

<=> is a good fit when:

Comparing two nullable columns directly in a WHERE or JOIN condition.
Negating equality on nullable data (NOT (a <=> b) is cleaner than the alternative).
Upsert / deduplication queries where you need exact matching including null identity.
Generated columns or audit logic where you want to detect whether a value actually changed, including transitions to/from NULL.

Caveats

MySQL and MariaDB only. The <=> operator is not part of the SQL standard and is not available in PostgreSQL, SQLite, or SQL Server. If your codebase runs tests against SQLite (a common Laravel setup), any <=> in a raw query will fail there.

PostgreSQL's equivalent is IS NOT DISTINCT FROM / IS DISTINCT FROM:

-- PostgreSQL equivalent of <=>
col IS NOT DISTINCT FROM val

-- PostgreSQL equivalent of NOT (col <=> val)
col IS DISTINCT FROM val

If cross-database portability matters, abstract the comparison behind a query scope or use the verbose but portable OR (IS NULL AND IS NULL) form.

Summary

The null-safe equality operator <=> is one of those small MySQL features that, once you know it exists, saves you from a whole class of subtle bugs. It's most valuable when you need to compare nullable columns directly — particularly in negated conditions where the standard != would silently swallow NULL rows. Just keep portability in mind: it's a MySQL/MariaDB extension, so make sure your test database matches your production database before reaching for it.

#best-practice #mysql #sql

🐥 Testing that Laravel events fire after a transaction commits

2026-06-16T17:00:00Z

A common source of bugs in Laravel applications is dispatching events inside a database transaction. Listeners often kick off their own queries or even their own transactions — and if the outer transaction hasn't committed yet, you can end up with deadlocks, stale reads, or listeners that act on data that gets rolled back.

The fix is straightforward: dispatch events after the transaction commits. But how do you write a test that actually enforces this? Here's a reusable pattern.

The problem

Consider an OrderAction that saves an order inside a transaction and then fires an OrderWasPlaced event:


final class PlaceOrderAction
{
    public function __invoke(Cart $cart): Order
    {
        DB::transaction(function () use ($cart) {
            $order = Order::create([...]);
            $order->lines()->createMany($cart->lines());
            
            // ❌ Event fired inside the transaction — listeners run
            //    while the order row is still locked.
            Event::dispatch(new OrderWasPlaced($order));
        });
    }
}

Any listener that tries to read the same rows will block (or deadlock) because the transaction still holds row locks.

The correct version moves the dispatch outside:


final class PlaceOrderAction
{
    public function __invoke(Cart $cart): Order
    {
        $order = null;

        DB::transaction(function () use ($cart, &$order) {
            $order = Order::create([...]);
            $order->lines()->createMany($cart->lines());
        });

        // ✅ Transaction has committed — listeners can safely read/write.
        Event::dispatch(new OrderWasPlaced($order));

        return $order;
    }
}

The test pattern

The key idea: register a real event listener before the action runs, and capture DB::transactionLevel() at the moment the event fires. If the event fires inside the transaction the level will be elevated; if it fires after the commit it will match the baseline.


use App\Actions\PlaceOrderAction;
use App\Events\OrderWasPlaced;
use Illuminate\Support\Facades\Bus;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Event;
use PHPUnit\Framework\Attributes\Test;
use Tests\TestCase;

final class PlaceOrderActionTest extends TestCase
{
    #[Test]
    public function it_dispatches_order_was_placed_after_the_transaction_commits(): void
    {
        // Fake jobs/queues so side-effect listeners don't cascade.
        Bus::fake();

        // Capture the DB nesting depth before the action runs.
        // LazilyRefreshDatabase / DatabaseTransactions wraps every test
        // in its own transaction, so the baseline is typically 1, not 0.
        $baselineLevel = DB::transactionLevel();
        $levelAtDispatch = null;

        // Register a real listener — do NOT call Event::fake(), otherwise
        // the dispatcher is replaced with a mock and no listeners run.
        Event::listen(OrderWasPlaced::class, function () use (&$levelAtDispatch) {
            $levelAtDispatch = DB::transactionLevel();
        });

        $cart = Cart::factory()->withLines(3)->create();

        app(PlaceOrderAction::class)($cart);

        $this->assertEquals(
            $baselineLevel,
            $levelAtDispatch,
            'OrderWasPlaced must be dispatched after the transaction commits, not inside it.',
        );
    }
}

Why compare against `$baselineLevel` instead of `0`?

Most Laravel test suites use LazilyRefreshDatabase or DatabaseTransactions, which wrap every test in an outer transaction for easy rollback. That means DB::transactionLevel() starts at 1 when the test body begins — not 0. Comparing against the snapshot taken before the action runs is always correct, regardless of your test database strategy.

Handling listener cascades

Sometimes the event you want to observe triggers further actions that write to the database, causing failures when those writes reference data that doesn't exist in the current test context. Two strategies:

1. Fake only the cascading action

If a listener dispatches a secondary action (e.g. StartFulfillmentAction), fake just that class so the chain stops there while leaving the event dispatcher intact:


Action::fake(StartFulfillmentAction::class);

The event still fires and your transaction-level listener still runs.

2. Fake only the jobs

If listeners queue jobs (Horizon, etc.), Bus::fake() is usually enough to prevent the cascade without touching the event system at all.

Checking multiple events

To assert that all the events fired by an action respect the post-commit invariant, collect them all in a single map:


$levels = [];

foreach ([OrderWasPlaced::class, InventoryReserved::class, InvoiceQueued::class] as $eventClass) {
    Event::listen($eventClass, function () use ($eventClass, &$levels) {
        $levels[$eventClass] = DB::transactionLevel();
    });
}

app(PlaceOrderAction::class)($cart);

foreach (array_keys($levels) as $eventClass) {
    $this->assertEquals(
        $baselineLevel,
        $levels[$eventClass],
        "{$eventClass} must be dispatched outside the transaction.",
    );
}

// Also assert every expected event actually fired.
$this->assertSame(
    [OrderWasPlaced::class, InventoryReserved::class, InvoiceQueued::class],
    array_keys($levels),
);

Quick reference

Scenario	Approach
Single event	`Event::listen()` + `DB::transactionLevel()` snapshot
Multiple events	Loop over event classes, collect levels into a map
Listener cascade breaks the test	`Action::fake(CascadingAction::class)` or `Bus::fake()`
Using `Event::fake()`	❌ Replaces the dispatcher — listeners never run, pattern breaks
Transaction depth varies by test setup	Always snapshot `$baselineLevel` before the action, never hardcode `0`

The pattern is lightweight — no mocking frameworks, no custom test doubles, just a listener closure and a single assertion. Once you've added it to one action test, it's easy to copy across the codebase anywhere you need to enforce the same invariant.

#laravel #database #best-practice #testing

🐥 Speeding up S3 uploads in GitHub Actions with Bash parallelism

2026-06-14T17:00:00Z

When you're uploading multiple directories to S3 (or an S3-compatible CDN like DigitalOcean Spaces) in a CI pipeline, the naive approach runs each upload sequentially. If you have three directories and each takes 30 seconds, you're waiting 90 seconds. They're completely independent — there's no reason not to run them at the same time.

Here's how to parallelize them with nothing but bash.

The problem

A typical multi-directory upload step looks like this:

- name: Upload to CDN
  run: |
    s3cmd put public/build s3://my-bucket/assets/ --recursive --acl-public
    s3cmd put public/img   s3://my-bucket/assets/ --recursive --acl-public
    s3cmd put public/js    s3://my-bucket/assets/ --recursive --acl-public

Each s3cmd put blocks until it's done before the next one starts. Wall-clock time = sum of all three.

The fix

- name: Upload to CDN
  run: |
    pids=()
    s3cmd put public/build s3://my-bucket/assets/ --recursive --acl-public & pids+=($!)
    s3cmd put public/img   s3://my-bucket/assets/ --recursive --acl-public & pids+=($!)
    s3cmd put public/js    s3://my-bucket/assets/ --recursive --acl-public & pids+=($!)
    for pid in "${pids[@]}"; do wait "$pid" || exit 1; done

Wall-clock time = duration of the slowest upload.

How it works

& pids+=($!) — The & runs the command in the background. $! is bash's special variable for the PID of the last backgrounded process, and we immediately append it to the pids array before starting the next job.

for pid in "${pids[@]}"; do wait "$pid" || exit 1; done — We wait for each background job by PID and fail the step immediately if any one of them exits with a non-zero code. This is important: a plain wait without arguments returns the exit code of the last process it waited for, which means a failure in the first or second upload could go undetected.

Why not just `wait`?

# Dangerous — only checks the exit code of the last job
s3cmd put public/build ... &
s3cmd put public/img   ... &
s3cmd put public/js    ... &
wait

If public/build fails but public/js succeeds, this exits 0 and your CI run goes green with a broken CDN.

Waiting by PID and checking each one individually gives you the same safety guarantee as running sequentially, at the speed of the fastest possible parallel execution.

The general pattern

This technique works for any set of independent shell commands you want to parallelize:

pids=()
some-command arg1 & pids+=($!)
some-command arg2 & pids+=($!)
some-command arg3 & pids+=($!)
for pid in "${pids[@]}"; do wait "$pid" || exit 1; done

No extra tooling, no GNU Parallel, no xargs — just bash.

#tools #devops #github

🐥 Debugging PHPUnit notices in Laravel parallel tests

2026-06-12T17:00:00Z

Running Laravel's test suite in parallel speeds things up considerably, but it also makes it easy to miss PHPUnit notices. The parallel worker output gets interleaved and buffered, and notices about deprecated API usage or risky tests tend to scroll past unnoticed — or disappear entirely. This post shows the command I use to surface them reliably.

The command

LARAVEL_PARALLEL_TESTING=1 \
LARAVEL_PARALLEL_TESTING_RECREATE_DATABASES=1 \
vendor/brianium/paratest/bin/paratest \
  --colors=always \
  --configuration=/path/to/phpunit.xml \
  --runner=\\Illuminate\\Testing\\ParallelRunner \
  --display-phpunit-notices \
  --fail-on-all-issues \
  tests/Unit

What each part does

Environment variables

LARAVEL_PARALLEL_TESTING=1 activates Laravel's parallel testing support. It causes the framework to spin up separate database connections per worker (suffixed _1, _2, etc.) and seed each one independently.

LARAVEL_PARALLEL_TESTING_RECREATE_DATABASES=1 forces those databases to be dropped and recreated from scratch on every run. Without it, a previous run's leftover state can cause tests to pass or fail for the wrong reasons — particularly relevant when you change a migration between runs.

Invoking paratest directly

Laravel's php artisan test --parallel is a thin wrapper around brianium/paratest. Calling the binary directly gives you access to flags that the Artisan wrapper doesn't expose, particularly the notice-related ones below.

--runner=\\Illuminate\\Testing\\ParallelRunner tells paratest to use Laravel's own runner class, which handles the database token injection and other framework-specific setup that the default runner skips.

--configuration takes an absolute path to your phpunit.xml. When you invoke paratest from outside the project root — for example, from a CI script or a Makefile — relative paths silently resolve to the wrong location. Using an absolute path avoids that class of silent misconfiguration.

Surfacing notices

--display-phpunit-notices is the key flag. PHPUnit emits notices for things like:

calls to deprecated assertion methods (assertContains on a string instead of assertStringContainsString)
tests marked @covers that cover no code
tests with no assertions when beStrictAboutTestsThatDoNotTestAnything is enabled

In a parallel run these notices are buffered per worker and often never reach the terminal. This flag ensures they are printed to output regardless.

--fail-on-all-issues treats any notice, warning, or deprecation as a test suite failure. This is what makes the command useful for CI: the exit code becomes non-zero the moment any worker emits a notice, so the pipeline fails and forces you to deal with it rather than letting it accumulate.

Scoping to `tests/Unit`

Passing tests/Unit as the path restricts the run to unit tests, which tends to surface notices faster than a full suite run because unit tests don't need a running server or real database queries. Once you've cleared the unit test notices, you can repeat with tests/Feature or omit the path entirely.

Reading the output

When a notice fires, paratest prints it alongside the failing worker output. The format looks like:

NOTICE  tests/Unit/Services/OrderServiceTest.php:42
Method Illuminate\Testing\Assert::assertContains() is deprecated. Use assertStringContainsString() instead.

The file path and line number point directly to the test method that triggered it. If you see the same notice repeating across many tests, the issue is usually in a shared base class or a trait — check the stack trace for the actual call site rather than fixing every test individually.

Making it a habit

The goal is to run with --fail-on-all-issues in CI from the start, before notices accumulate. If you're adding this to an existing codebase, it's usually easier to tackle notices test-file by test-file: run against a single file first, fix what you find, then broaden the path incrementally.

# Start with one file
LARAVEL_PARALLEL_TESTING=1 \
vendor/brianium/paratest/bin/paratest \
  --runner=\\Illuminate\\Testing\\ParallelRunner \
  --display-phpunit-notices \
  --fail-on-all-issues \
  tests/Unit/Services/OrderServiceTest.php

Once the file is clean, commit and move on to the next. The --fail-on-all-issues flag acts as a ratchet: once a file is notice-free, CI will catch any regression immediately.

#laravel #php #best-practice #testing

🐥 From N+1 to 1: Extracting paged PDF text with a single pdftotext call

2026-06-10T17:00:00Z

When building full-text search for uploaded documents, we needed to extract text page-by-page from PDFs so we could index each page as a separate chunk. The naive approach worked but was painfully slow. Here's how a single Unix insight cut it down to one process spawn.

The problem: N+1 process spawns

pdftotext is the standard Unix utility for extracting text from PDFs. It supports a -f (first page) and -l (last page) flag, so extracting a single page looks like this:

pdftotext -f 3 -l 3 document.pdf -

The natural implementation for paged extraction is to call this in a loop:


public function getPagedTextFromFile(string $path): Collection
{
    $pagedText = collect();

    $pageCount = $this->pdfInfoService->getPageCountFromFile($path);

    for ($i = 1; $i <= $pageCount; $i++) {
        $pagedText->put($i, $this->getRawTextFromFile($path, $i));
    }

    return $pagedText;
}

This is clean and obvious. It is also, for any document with real content, expensive:

1 pdfinfo call to get the page count
N pdftotext calls, one per page

Each call is a separate process spawn: the OS forks, loads the binary, opens the PDF, seeks to the requested page, extracts text, and exits. For a 50-page contract, that's 51 process spawns. On a server handling concurrent uploads, those 51 spawns happen in sequence, blocking the queue worker the entire time.

The insight: pdftotext already separates pages

Run pdftotext without page flags and pipe the output to a hex viewer:

pdftotext document.pdf - | cat -A | grep -P '\f'

You'll see form feed characters (\f, \x0C, ASCII 12) separating each page. This is standard — pdftotext has always done this. It's even documented in the man page, buried under the output format description.

That means the full multi-page text is already structured. We don't need N calls. We need one call and a string split.

The solution


public function getPagedTextFromFile(string $path): Collection
{
    $pagedText = collect();

    try {
        if ($this->mimeTypeForPath($path) !== 'application/pdf') {
            return $pagedText;
        }

        $result = $this->runExternalProcess(
            [config('pdftools.pdftotext'), $path, '-'],
            180
        );

        if ($result->getStdErr() !== '') {
            throw new Exception($result->getStdErr());
        }

        // pdftotext separates pages with \f; rtrim strips any optional trailing \f
        $pages = explode("\f", rtrim($result->getStdOut(), "\f"));

        foreach ($pages as $i => $pageText) {
            $pageText = trim($pageText, " \t\n\r\0\x0B");

            if ($pageText !== '') {
                $lines = $this->splitInLines($pageText);
                if (!empty($lines) && preg_match(self::DOCUSIGN_HEADER_PATTERN, $lines[0])) {
                    array_shift($lines);
                    $pageText = trim(implode("\n", $lines), " \t\n\r\0\x0B");
                }
            }

            $pagedText->put($i + 1, $pageText !== '' ? $pageText : null);
        }
    } catch (Exception $e) {
        Log::error("pdftotext | {$e->getMessage()}");
    }

    return $pagedText;
}

Before: 51 process spawns for a 50-page PDF.
After: 1 process spawn, regardless of page count.

For a 100-page document the old approach invoked pdftotext 100 times, each time reloading and re-parsing the entire PDF file to seek to one page. The new approach loads it once and returns everything.

Edge cases worth knowing

Trailing form feed. Some versions of pdftotext append a \f after the last page. Splitting "page1\fpage2\f" naively gives ["page1", "page2", ""] — an extra empty element. The rtrim($output, "\f") before splitting removes it cleanly.

Blank pages. A blank page produces an empty string after trimming. Storing null for it preserves correct page numbering for subsequent pages (page 5 stays page 5, even if pages 3 and 4 are blank). The downstream indexing code skips nulls, so blank pages don't pollute the search index.

Page-level headers. We strip DocuSign envelope headers (DocuSign Envelope ID: XXXXXXXX-...) from the beginning of any page that has one. Since the single-call output is split by page before this check, the per-page stripping logic is identical to the per-call approach — just applied after the split instead of inside each getRawTextFromFile call.

Non-PDF files. The MIME type check at the top of the method returns early for anything that isn't application/pdf. This replaces the earlier dependency on pdfinfo to get the page count — for non-PDFs that check would have returned 0 and short-circuited the loop, but the MIME check is simpler and removes the pdfinfo dependency from this path entirely.

The broader pattern

This is an instance of a general optimisation: if a tool is designed to process a whole file, don't call it once per chunk. The tool already knows how to walk the file efficiently; let it.

The same principle applies to:

ffprobe for video metadata — one call for all streams, not one call per stream
exiftool — batch mode processes a directory in one pass rather than per-file invocations
Database queries — SELECT with IN (...) instead of N individual selects
Meilisearch document uploads — one addDocuments call with a batch, not one call per document

In each case the per-item call pattern feels natural and is easy to reason about. But the overhead of repeatedly invoking a tool that was designed for whole-file processing accumulates fast once documents are large or queues are busy.

The fix, when it exists, is usually as simple as this one: read the man page, find the output format, split a string.

#pdf #development #php #tools #best-practice

🐥 The silent saboteur: how --quiet can break your Laravel command sequences

2026-06-08T17:00:00Z

When you chain multiple Artisan commands together in Laravel, there's a subtle trap waiting for you — one that's easy to miss because the commands still run, they just stop talking.

The setup

A common pattern in Laravel applications is a "meta-command" that runs a sequence of other commands in order. Think of a nightly job runner:


public function handle(): int
{
    $commandsToRun = [
        SomeCommand::class        => [],
        AnotherCommand::class     => [],
        DatabasePruneCommand::class => ['--quiet' => true],
        MoreCommands::class       => [],
        FinalCommand::class       => [],
    ];

    foreach ($commandsToRun as $commandToRun => $parameters) {
        $this->output->title($commandToRun);
        Artisan::call($commandToRun, $parameters, $this->output);
    }

    return self::SUCCESS;
}

You pass $this->output into each Artisan::call so the sub-command's output flows through to the console. Clean and straightforward.

The problem

One of your commands — say, a prune command — is noisy by default. You don't want its output cluttering the logs, so you pass '--quiet' => true. The title still appears, the command runs, everything looks fine.

Then you notice something odd: the commands after that quiet one stop printing their titles. The log files confirm they're running, but the console goes dark after that one --quiet call.

Why it happens

When Laravel processes the --quiet flag on a command, it calls:


$output->setVerbosity(OutputInterface::VERBOSITY_QUIET);

The key word is on the output object you passed in. Because you shared $this->output across all Artisan::call invocations, that single setVerbosity call mutates the object in place. Every subsequent command — and every title(), info(), or line() call — now runs against a quietly-configured output. They're suppressed silently, with no error.

The commands still execute; they just can't speak.

The fix

Capture the verbosity before each call and restore it immediately after:


foreach ($commandsToRun as $commandToRun => $parameters) {
    $this->output->title($commandToRun);

    $verbosity = $this->output->getVerbosity();
    Artisan::call($commandToRun, $parameters, $this->output);
    $this->output->setVerbosity($verbosity);
}

Two lines. The sub-command can do whatever it likes to the output during its run; your sequence always gets a clean slate for the next iteration.

The lesson

Shared mutable objects are the classic source of action-at-a-distance bugs. The output object here is a perfect example: you pass it in expecting read-like behaviour (writing to the terminal), but the callee has full write access to its configuration too.

A few takeaways:

Passing an object "for output" also grants mutation rights. Laravel's OutputStyle is stateful — verbosity, decorations, and more can be changed by anyone holding a reference.
Commands that still run aren't necessarily commands that are working correctly. Silent output suppression looks identical to "nothing went wrong" if you're only checking exit codes or log files.
Test the observable side effects, not just execution. A test that asserts title() is called N times would have caught this immediately; a test that only checks Artisan::call was invoked N times would not.

Bonus: write the test first

If you'd written this test before the bug appeared, you'd have been protected from day one:


public function it_restores_verbosity_so_quiet_commands_do_not_suppress_subsequent_output(): void
{
    // Simulate a sub-command that sets quiet mode
    Artisan::shouldReceive('call')
        ->twice()
        ->andReturnUsing(function () use ($output): int {
            $output->setVerbosity(OutputInterface::VERBOSITY_QUIET);
            return 0;
        });

    // Both titles must still appear
    $output->expects($this->exactly(2))->method('title');

    $this->subject->runSequenceOfCommands($command, [
        'first:command'  => [],
        'second:command' => [],
    ]);
}

Shared mutable state is everywhere in framework code. A little defensive save-and-restore goes a long way.

#development #laravel #best-practice

🐥 How to check how much memory a systemd unit is actually using

2026-06-06T17:00:00Z

When investigating memory usage on a Linux server, it's common to look at processes using tools such as top, htop, or ps. However, when applications are managed by systemd, it is often more useful to inspect memory usage at the service level rather than at the individual process level.

This is especially important for services that spawn multiple worker processes.

Using systemctl

The easiest way to see the memory usage of a systemd unit is:

systemctl status my-service.service

Example output:

Memory: 423.1M
CPU: 12min 34.567s

This value represents the total memory usage of the service's cgroup, including all child processes managed by the unit.

Using systemctl show

For scripting and automation, use:

systemctl show my-service.service --property=MemoryCurrent

Example:

MemoryCurrent=443662336

The value is returned in bytes.

To convert it to megabytes:

systemctl show my-service.service --property=MemoryCurrent --value \
    | awk '{ printf "%.2f MB\n", $1 / 1024 / 1024 }'

Inspecting the cgroup directly

Systemd tracks resource usage through Linux cgroups.

You can inspect the memory consumption directly:

cat /sys/fs/cgroup/system.slice/my-service.service/memory.current

Or locate the cgroup first:

systemctl show my-service.service --property=ControlGroup

Example:

ControlGroup=/system.slice/my-service.service

Then inspect the corresponding cgroup files.

Finding the processes behind a service

To see which processes belong to a unit:

systemctl status my-service.service

systemctl show my-service.service --property=MainPID

You can then inspect individual processes:

ps -o pid,rss,vsz,cmd -p <PID>

Keep in mind that summing RSS values from multiple processes can overestimate actual memory usage because shared memory pages may be counted multiple times.

Monitoring memory usage over time

For live monitoring:

watch -n 1 \
    'systemctl show my-service.service --property=MemoryCurrent --value'

Or use:

systemd-cgtop

This tool displays CPU, memory, and I/O usage per cgroup and is often the most convenient way to identify memory-hungry services on a system.

Configuring memory limits

Systemd can also enforce memory limits.

Example:

[Service]
MemoryMax=1G

After updating the unit file:

sudo systemctl daemon-reload
sudo systemctl restart my-service.service

To verify the configured limit:

systemctl show my-service.service --property=MemoryMax

Conclusion

For services managed by systemd, MemoryCurrent is usually the most accurate representation of how much memory the service is actually consuming. Unlike process-level tools, it accounts for the entire cgroup, making it ideal for monitoring applications that use worker pools, background jobs, or multiple child processes.

Useful commands to remember:

systemctl status my-service.service
systemctl show my-service.service --property=MemoryCurrent
systemd-cgtop

These provide a much clearer picture of service-level memory usage than inspecting individual processes alone.

#best-practice #linux #sysadmin

🐥 Fixing PHPUnit 13 with*() without expects() deprecations in Laravel tests

2026-06-04T17:00:00Z

After upgrading to PHPUnit 13, you may run into this deprecation warning in Laravel test suites:

Using with*() without expects() is deprecated and will no longer be possible in PHPUnit 14.

At first sight, the code often already looks correct:


$mock->expects($this->once())
    ->method('runSequenceOfCommands')
    ->with([...]);

So what is actually causing the warning?

The real issue

In many Laravel applications, the problem comes from using Laravel’s createPartialMock() helper together with newer PHPUnit versions.

Example:


$class = $this->createPartialMock(
    NightlyCommand::class,
    ['runSequenceOfCommands']
);

While this worked fine in older PHPUnit versions, PHPUnit 13 tightened internal mock expectation handling and now emits deprecation warnings in some cases when using Laravel’s wrapper helpers.

The fix

Instead of createPartialMock(), use PHPUnit’s native mock builder API.

Replace this:


$class = $this->createPartialMock(
    NightlyCommand::class,
    ['runSequenceOfCommands']
);

With this:


$class = $this->getMockBuilder(NightlyCommand::class)
    ->onlyMethods(['runSequenceOfCommands'])
    ->getMock();

And for multiple mocked methods:


$class = $this->getMockBuilder(NightlyCommand::class)
    ->onlyMethods([
        'runSequenceOfCommands',
        'confirm',
    ])
    ->getMock();

Why this works

getMockBuilder() uses PHPUnit’s modern native mock API directly, avoiding the legacy compatibility layer behind Laravel’s partial mock helpers.

This makes your tests:

compatible with PHPUnit 13
future-proof for PHPUnit 14
less dependent on framework-specific mock wrappers

Final result

Your expectations can stay exactly the same:


$class->expects($this->once())
    ->method('runSequenceOfCommands')
    ->with(
        $this->isInstanceOf(NightlyCommand::class),
        [
            // expected commands
        ]
    );

But by switching to getMockBuilder(), the deprecation warning disappears cleanly.

#laravel #php #best-practice #testing

🐥 Why crypto.getRandomValues() matters in JavaScript

2026-06-02T17:00:00Z

Generating random values sounds simple, until you need randomness that is actually secure.

A lot of JavaScript developers reach for Math.random() out of habit. While that works fine for visual effects, games, or non-critical IDs, it should never be used for anything security-sensitive.

That’s where the Web Crypto API comes in.

The problem with `Math.random()`

Math.random() is not cryptographically secure.

Its output is deterministic and predictable enough that an attacker may be able to reproduce or guess generated values under certain conditions.

That makes it unsuitable for:

Session tokens
Password reset links
API keys
CSRF tokens
Encryption keys
Secure identifiers

Example:

const id = Math.random().toString(36).slice(2)

This may look random, but it is not secure.

Using `crypto.getRandomValues()`

Modern browsers provide a secure random number generator through the Web Crypto API.

Example:

const bytes = new Uint8Array(16)

crypto.getRandomValues(bytes)

console.log(bytes)

This fills the typed array with cryptographically secure random bytes provided by the operating system.

Generating a secure random token

A common use case is generating secure tokens or identifiers.

function generateToken(length = 32) {
  const bytes = new Uint8Array(length)

  crypto.getRandomValues(bytes)

  return Array.from(bytes)
    .map(byte => byte.toString(16).padStart(2, "0"))
    .join("")
}

console.log(generateToken())

Example output:

4f8b7d3a1f9e0c8d7a2b6c5d4e3f1a9c

This is significantly safer than using Math.random().

Typed arrays are required

crypto.getRandomValues() only works with integer-based typed arrays.

Supported examples include:

new Uint8Array(32)
new Uint16Array(16)
new Int32Array(8)

This will fail:

crypto.getRandomValues([])

Because regular JavaScript arrays are not supported.

Browser and runtime support

crypto.getRandomValues() is widely supported in modern browsers.

It is also available in runtimes like:

Node.js
Deno
Bun

Example in Node.js:

const bytes = new Uint8Array(16)

crypto.getRandomValues(bytes)

console.log(bytes)

In older Node.js versions, developers typically used:

require("crypto").randomBytes(16)

UUID generation

If your goal is generating UUIDs, modern runtimes also support:

crypto.randomUUID()

Example:

550e8400-e29b-41d4-a716-446655440000

Internally, this also uses cryptographically secure randomness.

Things to remember

Use Math.random() for non-security-related randomness only
Use crypto.getRandomValues() for anything security-sensitive
Prefer crypto.randomUUID() when generating UUIDs
Always generate randomness using the operating system’s secure RNG

For modern JavaScript applications, crypto.getRandomValues() should be the default choice whenever security matters.

#javascript #best-practice #auth

🐥 How to find all Jira issues ever assigned to someone (even historical ones)

2026-05-31T17:00:00Z

If you've ever tried to pull up all the tickets that Sarah Mitchell worked on last year, you've probably started with the obvious query:

assignee = "sarah.mitchell@example.com"

And then realised it only shows her current tickets — not the ones she handed off to Tom Bergkamp or closed six months ago.

Here's the fix.

The `was` operator

Jira's JQL has a was operator that checks the change history of a field, not just its current value. So to find every issue Sarah was ever assigned to:

assignee was "sarah.mitchell@example.com"

Simple, but powerful.

Checking multiple people at once

Need to audit the work of an entire sub-team? Use was in with a list:

assignee was in ("sarah.mitchell@example.com", "tom.bergkamp@example.com", "priya.nair@example.com")

This returns any issue that was assigned to any of those three people at any point in time.

Scoping to a specific year

Combine it with the during clause to limit results to a time window — useful for annual reviews, retrospectives, or handover audits:

assignee was in ("sarah.mitchell@example.com", "tom.bergkamp@example.com") during ("2025-01-01", "2025-12-31")

This only matches issues where one of them was the assignee at some point during 2025 — even if the ticket has since been reassigned or closed.

Putting it all together

A full, practical query might look like this:

project = "PLATFORM"
AND assignee was in ("sarah.mitchell@example.com", "tom.bergkamp@example.com")
AND during ("2025-01-01", "2025-12-31")
ORDER BY updated DESC

The was operator works on other fields too — status was "In Progress", priority was "High", etc. — so it's worth keeping in your JQL toolkit whenever you need to query history rather than current state.

#tools #best-practice

🐥 Downloading external images as squares from a Phoenix app

2026-05-29T17:00:00Z

A common need in admin tools: click a button, download a remote image as a square JPEG. Simple enough — until CORS gets in the way.

The CORS problem

When fetching a cross-origin image and drawing it onto a , the browser marks the canvas as "tainted". The moment you call canvas.toBlob() to read the pixel data back out, it throws a security error. Unless the image server sends explicit CORS headers — which most don't — you can't do canvas operations on cross-origin images.

The fix: a server-side proxy

The solution is to proxy the image through the Phoenix app. From the browser's point of view the image comes from the same origin, so the canvas stays clean.

def image_proxy(conn, %{"url" => url}) do
  with true <- allowed_url?(url),
       {:ok, response} <- Req.get(url) do
    content_type =
      response.headers
      |> Map.get("content-type", ["image/jpeg"])
      |> List.first()
      |> String.split(";")
      |> hd()

    conn
    |> put_resp_content_type(content_type)
    |> send_resp(200, response.body)
  else
    false -> send_resp(conn, 400, "Invalid URL")
    _ -> send_resp(conn, 502, "Failed to fetch image")
  end
end

The allowed_url?/1 function validates the host against a known allowlist — an important SSRF guard so the proxy can't be abused to fetch arbitrary internal URLs.

Center-cropping to a square in the browser

Once the image loads from the proxy, a small Canvas API snippet handles the crop. The logic is straightforward: use the shorter dimension as the square size, then offset into the longer dimension by half the difference to take the center slice.

window.addEventListener("phx:download-square-image", (event) => {
  const { url, filename } = event.detail;
  const proxyUrl = `/image-proxy?url=${encodeURIComponent(url)}`;

  const img = new Image();
  img.onload = () => {
    const size = Math.min(img.naturalWidth, img.naturalHeight);
    const canvas = document.createElement("canvas");
    canvas.width = size;
    canvas.height = size;

    const ctx = canvas.getContext("2d");
    const offsetX = (img.naturalWidth - size) / 2;
    const offsetY = (img.naturalHeight - size) / 2;
    ctx.drawImage(img, offsetX, offsetY, size, size, 0, 0, size, size);

    canvas.toBlob((blob) => {
      const a = document.createElement("a");
      a.href = URL.createObjectURL(blob);
      a.download = filename;
      a.click();
      URL.revokeObjectURL(a.href);
    }, "image/jpeg", 0.95);
  };
  img.src = proxyUrl;
});

For a landscape image the left and right edges are trimmed, keeping the center. For a portrait image the top and bottom are trimmed instead. The full shorter dimension is always preserved — no upscaling, no padding.

Wiring it up in LiveView

The download is triggered from the template using Phoenix's JS.dispatch/2, which fires a custom DOM event with the image URL and filename as detail:

<button
  class="cursor-pointer"
  phx-click={
    JS.dispatch("phx:download-square-image",
      detail: %{url: @image_url, filename: "image.jpg"}
    )
  }
>
  Download
button>

No LiveView round-trip needed — JS.dispatch fires the event directly in the browser, the window listener catches it, and the download happens entirely client-side after the one proxy fetch.

Why `naturalWidth` instead of `width`?

img.width returns the CSS-rendered size, which is meaningless for an image that isn't attached to the DOM. img.naturalWidth always returns the actual pixel dimensions of the image data — the right value to use when doing pixel-level canvas operations.

#javascript #frontend #elixir #phoenix

🐥 The Tailwind `enabled:` selector trick for disabled buttons

2026-05-27T17:00:00Z

When you add a disabled attribute to a

🐥 Hide a layout section from a specific child view in Laravel Blade

2026-05-25T17:00:00Z

Sometimes you have a shared layout that renders a block — a promotional banner, a sidebar widget, an image — that makes sense on most pages but not all. Rather than duplicating the layout or reaching for JavaScript, you can solve this cleanly with two built-in Blade directives: @section and View::hasSection().

The problem

Say your login layout renders a decorative image at the bottom of every page:

{{-- resources/views/layouts/login.blade.php --}}
@php $loginImage = Contractify::loginImage(); @endphp
@if ($loginImage->src)
    
        src }}" alt="{{ $loginImage->alt }}">
    
@endif

This is fine for the login and registration pages, but on the OAuth authorization page it's visual noise you'd rather skip.

The solution

Step 1 — Wrap the block in the layout with @unless(View::hasSection(...)):

{{-- resources/views/layouts/login.blade.php --}}
@unless(View::hasSection('hide-login-image'))
    @php $loginImage = Contractify::loginImage(); @endphp
    @if ($loginImage->src)
        
            src }}" alt="{{ $loginImage->alt }}">
        
    @endif
@endunless

Step 2 — Declare the empty section in the child view that should opt out:

{{-- resources/views/vendor/passport/authorize.blade.php --}}
@extends('layouts.login')

@section('hide-login-image')@endsection

@section('content')
    {{-- ... --}}
@endsection

How it works

View::hasSection('hide-login-image') returns true if the currently-rendering child view has declared a section with that name — even an empty one. The @unless then skips the block entirely.

Every other view that extends the layout leaves that section undeclared, so hasSection returns false and the image renders as normal.

Why this is better than the alternatives

No layout duplication. You keep a single source of truth.
No conditionals based on route names or controller names. Those couple your layout to your routing.
The opt-out lives in the view that needs it. Easy to find, easy to remove.

It's a tiny pattern, but it keeps your layouts clean and your child views in control of their own presentation.

#frontend #laravel #best-practice

🐥 Scanning files with clamdscan and --fdpass

2026-05-23T17:00:00Z

When integrating antivirus scanning into a Linux application or upload pipeline, clamdscan is usually a much better choice than clamscan.

While clamscan starts a full standalone scan process and loads virus signatures every time, clamdscan talks to the long-running clamd daemon. This makes scans significantly faster and more suitable for production environments.

One particularly useful option is --fdpass.

What does --fdpass do?

Normally, clamd runs under its own user account, such as clamav. This can create permission issues when scanning files owned by another user or temporary upload files.

The --fdpass option solves this by passing the already opened file descriptor to the daemon instead of letting the daemon reopen the file itself.

This is especially useful for:

Upload processing
Temporary files
Restricted file permissions
CI/CD pipelines
Web applications

Installing ClamAV

On Debian or Ubuntu systems:

sudo apt update
sudo apt install clamav clamav-daemon

Update the virus definitions:

sudo freshclam

Enabling clamd on startup

To ensure the daemon automatically starts after a reboot:

sudo systemctl enable clamav-daemon
sudo systemctl start clamav-daemon

Verify the service is running:

sudo systemctl status clamav-daemon

On some distributions, the service may be named clamd instead.

Verifying the socket configuration

clamdscan communicates with the daemon through a Unix socket.

Check the configured socket path:

grep LocalSocket /etc/clamav/clamd.conf

Typical values are:

LocalSocket /run/clamav/clamd.ctl

or:

LocalSocket /var/run/clamav/clamd.ctl

You can also locate the socket manually:

sudo find /run /var/run -name "*.ctl"

Scanning a file

To scan a file quietly:

clamdscan --fdpass --quiet myfile.zip

If the file is clean, the command exits with status code 0.

If malware is detected, the exit code becomes 1.

Example in a shell script:

if clamdscan --fdpass --quiet upload.pdf; then
    echo "File is clean"
else
    echo "Virus detected"
fi

Why use clamdscan instead of clamscan?

clamdscan has several advantages:

Much faster scanning
Lower memory usage
Better suited for concurrent workloads
No repeated signature loading
Ideal for web servers and APIs

For applications handling many uploads or background jobs, using clamdscan --fdpass is generally the recommended setup.

Common error

If you encounter:

ERROR: Could not connect to clamd on LocalSocket

the daemon is usually not running.

Start it manually:

sudo systemctl start clamav-daemon

Then retry the scan command.

Understanding exit codes

When integrating clamdscan into an application or upload pipeline, it is important to distinguish between an actual virus detection and a technical failure.

Fortunately, clamdscan provides clear exit codes for this.

Exit code	Meaning
`0`	No virus found
`1`	Virus found
`2`	Scanner error or operational failure

This means you should avoid parsing stdout or stderr to determine the scan result. Instead, rely on the process exit code directly.

Example:

clamdscan --fdpass --quiet upload.pdf
result=$?

case $result in
    0)
        echo "File is clean"
        ;;
    1)
        echo "Virus detected"
        ;;
    2)
        echo "Scan failed"
        ;;
esac

This distinction is especially important in automated systems:

Exit code 1 means the scanner worked correctly and detected malware
Exit code 2 means something operational failed, such as:
- clamd not running
- socket connection failures
- permission issues
- corrupted scanner configuration

In production systems, a virus detection is usually a business-level validation failure, while exit code 2 should typically trigger retries, logging, monitoring, or alerts.

#tools #best-practice #devops #linux #sysadmin

🐥 TypeScript's Pick utility type: select what you need

2026-05-21T17:00:00Z

TypeScript ships with a set of built-in utility types that make working with existing types far more ergonomic. One of the most useful is Pick — a simple but powerful tool for carving out a subset of properties from a larger type.

What Is `Pick`?

Pick constructs a new type by selecting a specific set of properties (Keys) from an existing type (Type). Think of it as a projection: you have a big object shape, and you only want a slice of it.

type Pick<T, K extends keyof T> = {
  [P in K]: T[P];
};

A Practical Example

Suppose you have a User type across your application:

type User = {
  id: number;
  name: string;
  email: string;
  passwordHash: string;
  createdAt: Date;
  role: 'admin' | 'editor' | 'viewer';
};

When building a public-facing API response, you never want to expose passwordHash. And a user profile card in the UI might only care about id, name, and email. Instead of duplicating the shape or manually re-declaring those fields, reach for Pick:

type PublicUser = Pick<User, 'id' | 'name' | 'email'>;

// Equivalent to:
// type PublicUser = {
//   id: number;
//   name: string;
//   email: string;
// };

Now PublicUser stays in sync with User automatically. If you rename name to fullName on User, TypeScript will immediately flag any Pick references to 'name' as an error.

Real-World Use Cases

Form State

When a form only edits a subset of a model's fields, Pick keeps the shape accurate without duplication:

type UpdateProfileForm = Pick<User, 'name' | 'email'>;

function submitProfileUpdate(data: UpdateProfileForm): Promise<void> {
  return api.patch('/profile', data);
}

Component Props

Vue and React components often need just a few fields from a larger model. Pick makes this explicit in the prop type:

type AvatarProps = Pick<User, 'id' | 'name'> & {
  size?: 'sm' | 'md' | 'lg';
};

Service Layer Boundaries

When passing data between services, Pick enforces that only the relevant fields cross the boundary — a lightweight form of data encapsulation:

type EmailPayload = Pick<User, 'name' | 'email'>;

function sendWelcomeEmail(user: EmailPayload): void {
  mailer.send({
    to: user.email,
    subject: `Welcome, ${user.name}!`,
  });
}

Combining with Other Utility Types

Pick composes cleanly with other utilities. For example, Partial> gives you an optional subset — perfect for PATCH request bodies:

type PatchUserRequest = Partial<Pick<User, 'name' | 'email' | 'role'>>;

`Pick` vs `Omit`

Pick and Omit are mirror images of each other:

Utility	Approach	Best when…
`Pick`	Allowlist — name what you want	The desired set is small
`Omit`	Denylist — name what you don't want	The excluded set is small

If you want all fields except one or two, Omit is more concise. If you want just a handful of fields from a large type, Pick is cleaner.

// These are equivalent when User has exactly these five fields:
type WithoutPassword = Omit<User, 'passwordHash'>;
type SafeFields = Pick<User, 'id' | 'name' | 'email' | 'createdAt' | 'role'>;

// Prefer Omit here — fewer keys to list

Key Takeaways

Pick creates a new type with only the named properties from Type.
The Keys argument is validated against keyof Type at compile time — typos are caught immediately.
It keeps derived types in sync with their source; renames and removals surface as errors rather than silent mismatches.
It composes well with Partial, Required, Readonly, and Omit for expressive, minimal type definitions.

Whenever you find yourself re-declaring a handful of fields that already exist on another type, Pick is almost certainly the right tool.

#typescript #frontend #best-practice

🐥 Color-code your GitHub PR list with custom CSS

2026-05-19T17:00:00Z

If you spend a lot of time reviewing pull requests on GitHub, you've probably wished the PR list gave you more visual signal at a glance. Which PRs are approved and ready to merge? Which ones have a reviewer blocking them? Which are still drafts?

With the Refined GitHub browser extension and a few lines of custom CSS, you can color-code your PR list to answer all of those questions instantly.

What You'll Need

Refined GitHub — a browser extension for Chrome, Firefox, and Safari that enhances the GitHub UI with dozens of quality-of-life improvements. One of its lesser-known features is the ability to inject your own custom CSS.

Setting Up Custom CSS in Refined GitHub

Install Refined GitHub from your browser's extension store.
Click the Refined GitHub icon in your toolbar and open its Options page.
Scroll down to the Custom CSS section.
Paste the CSS below and save.

The CSS

/* Draft PRs — targets the draft octicon on the PR status icon */
.js-issue-row:has(svg.octicon-git-pull-request-draft) {
    border-right: 4px solid #e68934 !important;
    background-color: rgba(230,137,52,0.1);
}

/* At least one approving review */
.js-issue-row:has([aria-label*="review approval"]) {
    border-right: 4px solid #5eb4a7;
    background-color: rgba(94, 180, 167, 0.2);
}

/* Changes Requested */
.js-issue-row:has([aria-label*="review requesting changes"]),
.js-issue-row:has([title="Changes requested"]) {
    border-right: 4px solid #9b59b6;
    background-color: rgba(155,89,182,0.1) !important;
}

How It Works

GitHub's PR list uses SVG status icons and review-state badges to indicate a PR's current state. The CSS uses the :has() selector to look up from those indicators to the parent row and apply a colored right border and tinted background.

Selector	Meaning	Color
`svg.octicon-git-pull-request-draft`	Draft PR	Orange `#e68934`
`[aria-label*="review approval"]`	Approved	Teal `#5eb4a7`
`[aria-label*="review requesting changes"]`	Changes requested	Purple `#9b59b6`

The Result

Head to any GitHub PR list and you'll immediately see rows highlighted by status. Approved PRs glow teal, blocked ones turn purple, and drafts stand out in orange — no more scanning each row individually.

It's a small change, but when you're triaging dozens of open PRs every day, the visual grouping saves a surprising amount of time.

#css #tools #github

🐥 Why Dexter LSP doesn't autocomplete Elixir stdlib modules

2026-05-17T17:00:00Z

If you're using Dexter as your Elixir LSP in VS Code and wondering why String, Enum, and other standard library modules don't show up in autocomplete — the answer is likely a missing or misconfigured stdlibPath.

The Problem

Dexter needs access to the Elixir source files (.ex) to index the stdlib. When you install Elixir via Homebrew, only compiled .beam files are included — no source. So even if you point dexter.stdlibPath at something like:

"dexter.stdlibPath": "/opt/homebrew/opt/elixir/lib/elixir/lib"

...there's nothing for Dexter to index, and stdlib autocomplete silently doesn't work.

The Fix

Clone the Elixir source at the version matching your runtime:

elixir --version
git clone https://github.com/elixir-lang/elixir.git ~/elixir-src --depth=1 --branch v1.18.3

Then update your .vscode/settings.json:

"dexter.stdlibPath": "/Users/yourname/elixir-src/lib"

That lib/ directory contains subdirectories like elixir/lib/, mix/lib/, logger/lib/, etc. — all with proper .ex source files that Dexter can index for autocomplete.

After restarting VS Code, stdlib completions for String, Enum, Map, and friends should start appearing.

#development #best-practice #elixir #vscode

🐥 Keeping Elixir stdlib source in sync with your project

2026-05-15T17:00:00Z

When working with tools like Dexter for Elixir code intelligence in VS Code, it's useful to have the Elixir standard library source checked out locally. Dexter uses it to provide go-to-definition and hover docs for stdlib modules.

The naive approach — cloning it once by hand — breaks down the moment you upgrade Elixir. You forget to re-clone, the path is wrong, and suddenly your editor is jumping to source that doesn't match what's actually running.

Here's a small shell script that automates it.

The script

#!/usr/bin/env bash
set -euo pipefail

version=$(elixir --version | grep -oE 'Elixir [0-9]+\.[0-9]+\.[0-9]+' | head -1 | awk '{print $2}')

if [[ -z "$version" ]]; then
  echo "Error: could not determine Elixir version" >&2
  exit 1
fi

branch="v${version}"
dest="$(cd "$(dirname "$0")" && pwd)/.elixir_stdlib"

echo "Elixir version: ${version}"

if [[ -d "$dest" ]]; then
  if git -C "$dest" tag --points-at HEAD 2>/dev/null | grep -qx "$branch"; then
    echo "${dest} already at ${branch}, skipping."
    exit 0
  fi
  echo "Found ${dest} at a different version, removing for ${branch} ..."
  rm -rf "$dest"
fi

echo "Cloning branch ${branch} into ${dest} ..."
git -c advice.detachedHead=false clone https://github.com/elixir-lang/elixir.git "$dest" --depth=1 --branch "$branch"

What it does

Detects the running Elixir version. It calls elixir --version and extracts the version number, so there's no hardcoded version to keep in sync manually.

Clones into .elixir_stdlib next to the script. Using dirname "$0" makes the destination relative to the script itself, so it works regardless of your current working directory.

Skips the clone if already up to date. Before doing anything destructive, it checks whether the target tag (v1.19.5, for example) is among the tags pointing at HEAD in the existing clone. This matters because the Elixir repo uses floating tags like v1.19-latest that point at the same commit — a naive git describe would return that tag instead, causing a false version mismatch every time.

Wipes and re-clones on version change. If the installed Elixir version doesn't match what's checked out, the old folder is removed and the correct version is cloned fresh.

Suppresses the detached HEAD warning. Cloning a tag always results in a detached HEAD, which git warns about by default. Passing -c advice.detachedHead=false silences that noise without hiding anything useful.

Usage

Drop the script in your project root, make it executable, add .elixir_stdlib to .gitignore, and point your editor at ${workspaceFolder}/.elixir_stdlib/lib.

chmod +x clone-elixir-src.sh
./clone-elixir-src.sh

Run it again whenever you upgrade Elixir — it'll figure out the rest.

#development #tools #best-practice #elixir #terminal #vscode

🐥 Anti-Corruption Layer in Elixir/Phoenix - Keep your domain clean

2026-05-13T17:00:00Z

When you integrate an external service — a payment provider, a shipping API, a CRM — you face a quiet but persistent risk: the external system's model starts leaking into your own. Status strings, provider-specific IDs, and SDK structs end up scattered across your business logic. Changing providers later means touching code you should never have had to change.

The Anti-Corruption Layer (ACL) is a pattern from Domain-Driven Design that puts an explicit translation boundary between your domain and the external world. Everything provider-specific lives in one place. Your domain never knows it exists.

This post walks through implementing it in Elixir and Phoenix, using a payment integration as the running example.

The Problem

Suppose you're integrating Stripe directly. Without a boundary, it's easy to write something like this:

defmodule MyApp.Orders do
  def complete_order(order) do
    case Req.post("https://api.stripe.com/v1/payment_intents",
           auth: {:basic, stripe_key()},
           form: [amount: order.total_cents, currency: "eur", confirm: true]
         ) do
      {:ok, %{status: 200, body: %{"status" => "succeeded"} = intent}} ->
        Orders.mark_paid(order, intent["id"])

      {:ok, %{body: %{"error" => %{"message" => msg}}}} ->
        {:error, msg}
    end
  end
end

This works on day one. But now your Orders context knows that payments have a "succeeded" status string, that IDs come from intent["id"], and that Stripe's API lives at that specific URL. If you ever swap providers — or just want to test without hitting Stripe — you have to unpick all of this from business logic.

Core Concepts in Elixir

The ACL pattern maps cleanly to Elixir idioms:

DDD concept	Elixir equivalent
Domain model	Plain `defstruct` (not an Ecto schema)
Port / interface	A `@behaviour` module
ACL implementation	A module implementing the behaviour
Domain service	A context module that only calls the behaviour
Wiring	`Application.get_env/2` and config files

Step 1: Define Your Domain Structs

These live in your domain and use your language — not Stripe's.

defmodule Billing.PaymentResult do
  @type status :: :pending | :captured | :declined | :refunded

  @enforce_keys [:id, :status, :amount_cents, :currency]
  defstruct [:id, :status, :amount_cents, :currency]
end

defmodule Billing.PaymentEvent do
  @type type :: :payment_captured | :payment_declined | :payment_refunded

  @enforce_keys [:type, :payment_id, :amount_cents]
  defstruct [:type, :payment_id, :amount_cents]
end

No Stripe types, no raw maps, no magic strings. If you switch providers, these structs stay exactly as they are.

Step 2: Define the Port Behaviour

The behaviour declares what the domain needs — a contract, not an implementation.

defmodule Billing.PaymentGateway do
  @type charge_result :: {:ok, Billing.PaymentResult.t()} | {:error, String.t()}
  @type refund_result :: {:ok, Billing.PaymentResult.t()} | {:error, String.t()}

  @callback charge(amount_cents :: integer(), currency :: String.t(), source :: String.t()) ::
              charge_result()

  @callback refund(payment_id :: String.t()) :: refund_result()
end

The domain context will call through this behaviour. It never imports Stripe modules or touches raw HTTP responses.

Step 3: Implement the ACL

This is the only module allowed to know anything about Stripe. All HTTP calls and all translation logic live here.

defmodule Billing.Gateways.StripeGateway do
  @behaviour Billing.PaymentGateway

  @base_url "https://api.stripe.com/v1"

  @impl true
  def charge(amount_cents, currency, source) do
    response =
      Req.post!("#{@base_url}/payment_intents",
        auth: {:basic, secret_key()},
        form: [
          amount: amount_cents,
          currency: currency,
          payment_method: source,
          confirm: true,
          "automatic_payment_methods[enabled]": true,
          "automatic_payment_methods[allow_redirects]": "never"
        ]
      )

    case response.status do
      200 -> {:ok, translate_intent(response.body)}
      _ -> {:error, response.body["error"]["message"]}
    end
  end

  @impl true
  def refund(payment_id) do
    response =
      Req.post!("#{@base_url}/refunds",
        auth: {:basic, secret_key()},
        form: [payment_intent: payment_id]
      )

    case response.status do
      200 -> {:ok, translate_refund(response.body)}
      _ -> {:error, response.body["error"]["message"]}
    end
  end

  # --- Translation layer ---

  defp translate_intent(intent) do
    %Billing.PaymentResult{
      id: intent["id"],
      status: translate_status(intent["status"]),
      amount_cents: intent["amount"],
      currency: intent["currency"]
    }
  end

  defp translate_refund(refund) do
    %Billing.PaymentResult{
      id: refund["payment_intent"],
      status: :refunded,
      amount_cents: refund["amount"],
      currency: refund["currency"]
    }
  end

  defp translate_status("succeeded"), do: :captured
  defp translate_status("processing"), do: :pending
  defp translate_status("requires_payment_method"), do: :declined
  defp translate_status("canceled"), do: :declined
  defp translate_status(_), do: :pending

  defp secret_key, do: Application.fetch_env!(:my_app, :stripe_secret_key)
end

Pattern matching on translate_status/1 makes the translation explicit and exhaustive. Adding a new Stripe status is a one-line change in exactly one place.

Step 4: Write a Clean Domain Context

The Billing context only speaks the behaviour. It has no idea which gateway is wired up.

defmodule Billing do
  def process_payment(amount_cents, currency, source) do
    gateway().charge(amount_cents, currency, source)
  end

  def issue_refund(payment_id) do
    gateway().refund(payment_id)
  end

  defp gateway do
    Application.get_env(:my_app, :payment_gateway, Billing.Gateways.StripeGateway)
  end
end

Nothing in here ties you to Stripe. The context is pure business logic.

Step 5: Wire It Up in Config

# config/config.exs
config :my_app, :payment_gateway, Billing.Gateways.StripeGateway
config :my_app, :stripe_secret_key, System.get_env("STRIPE_SECRET_KEY")

# config/test.exs
config :my_app, :payment_gateway, Billing.Gateways.FakeGateway

Switching providers in production means changing one config line and shipping a new gateway module. Nothing else changes.

Handling Webhooks

Webhooks are where external models are most tempting to let through. A Phoenix controller should translate immediately and dispatch a domain event — it should not pass raw Stripe payloads any further.

defmodule MyAppWeb.StripeWebhookController do
  use MyAppWeb, :controller

  def handle(conn, params) do
    case translate_event(params) do
      {:ok, event} ->
        Billing.handle_payment_event(event)
        send_resp(conn, 200, "")

      {:error, :unhandled} ->
        send_resp(conn, 200, "")

      {:error, reason} ->
        send_resp(conn, 400, reason)
    end
  end

  defp translate_event(%{
         "type" => "payment_intent.succeeded",
         "data" => %{"object" => %{"id" => id, "amount" => amount}}
       }) do
    {:ok, %Billing.PaymentEvent{type: :payment_captured, payment_id: id, amount_cents: amount}}
  end

  defp translate_event(%{
         "type" => "payment_intent.payment_failed",
         "data" => %{"object" => %{"id" => id, "amount" => amount}}
       }) do
    {:ok, %Billing.PaymentEvent{type: :payment_declined, payment_id: id, amount_cents: amount}}
  end

  defp translate_event(_), do: {:error, :unhandled}
end

The controller is the ACL for inbound Stripe events. Once translated, Billing.handle_payment_event/1 receives only %Billing.PaymentEvent{} structs — never raw Stripe data.

Testing Without a Real Gateway

Because the gateway is a behaviour, you can swap in a fake implementation for tests without mocks or HTTP stubs.

defmodule Billing.Gateways.FakeGateway do
  @behaviour Billing.PaymentGateway

  @impl true
  def charge(_amount_cents, _currency, "fail_card") do
    {:error, "Card declined"}
  end

  def charge(amount_cents, currency, _source) do
    {:ok, %Billing.PaymentResult{
      id: "fake_#{System.unique_integer([:positive])}",
      status: :captured,
      amount_cents: amount_cents,
      currency: currency
    }}
  end

  @impl true
  def refund(payment_id) do
    {:ok, %Billing.PaymentResult{
      id: payment_id,
      status: :refunded,
      amount_cents: 0,
      currency: "eur"
    }}
  end
end

Your tests call Billing.process_payment/3 exactly as production code does — there is no test-only branch in the domain logic, and no HTTP traffic.

test "successful payment returns a captured result" do
  assert {:ok, %Billing.PaymentResult{status: :captured}} =
           Billing.process_payment(1999, "eur", "tok_visa")
end

test "declined card returns an error" do
  assert {:error, "Card declined"} =
           Billing.process_payment(1999, "eur", "fail_card")
end

Elixir-Specific Considerations

Behaviours vs. protocols. Use a @behaviour when you have multiple implementations of the same concept (payment gateways, SMS providers). Use a protocol when you want polymorphism across data types you don't control. For the ACL pattern, behaviours are the right tool.

Pattern matching is your translation engine. The translate_status/1 clauses above are cleaner than a case block or a map lookup. If Stripe adds a new status you haven't handled, the _ clause captures it safely, and you can add a specific clause when you care about it.

Keep Ecto schemas out of the ACL. It's tempting to map directly from a Stripe response onto an Ecto schema. Resist this. Plain structs are easier to reason about, test, and evolve independently from your database shape. Persist only after your domain logic has run.

Stateful gateways. If your gateway implementation needs its own process — say, to maintain an authenticated session or a connection pool — start it in your application's supervision tree. The behaviour contract stays the same; the implementation just has a start_link/1 that gets wired into the supervisor.

Common Pitfalls

Returning raw maps from the gateway. If charge/3 returns %{"id" => ..., "status" => "succeeded"}, you've moved the contamination rather than removed it. Always return your own structs.

Putting translation in the Phoenix controller for everything. The controller is the right place for webhook translation (it's the entry point). But if you're doing translation inside action handlers for outgoing calls, extract it into the gateway module where it belongs.

One ACL module for all external systems. If you add a shipping provider, create Shipping.Gateways.DHLGateway with its own behaviour. Don't grow StripeGateway into a general-purpose external-systems module.

Letting provider IDs become first-class domain concepts. Storing a Stripe payment intent ID as billing_stripe_id in your domain is a smell — the domain now knows about Stripe. Store it as external_payment_id or in a separate gateway-specific record that your ACL manages.

Conclusion

Elixir's behaviours give you a clean, compiler-checked way to define the boundary between your domain and the outside world. Pattern matching makes the translation logic readable and exhaustive. Swapping configs gives you test isolation without mocks.

The ACL pattern keeps your core business logic stable regardless of what external APIs do. When Stripe changes a status code or you decide to try a different provider, you update one module. Your domain, your tests, and everything that depends on them stays untouched.

#development #pattern #best-practice #elixir #phoenix

🐥 Restarting supervisord daemons by working directory on Linux

2026-05-11T17:00:00Z

When you run multiple instances of the same Laravel Horizon worker (or any supervisord-managed process) across different deployment directories, you'll quickly notice that supervisord assigns generic auto-generated names like daemon-282661:daemon-282661_00. There's no obvious way to tell which daemon belongs to which application directory — until you know the trick.

Finding the working directory of a process

On Linux, every running process exposes its current working directory as a symlink under /proc:

readlink /proc/<pid>/cwd

To check all your Horizon workers at once, grab their PIDs from supervisorctl status and loop over them:

for pid in 91286 91287 91288 91290; do
  echo "$pid: $(readlink /proc/$pid/cwd)"
done

Restarting daemons for a specific directory

Once you can map PIDs to directories, it's straightforward to build a script that restarts only the daemons running from a given path:

#!/bin/bash

TARGET_DIR="${1:?Usage: $0 }"
TARGET_DIR=$(realpath "$TARGET_DIR")

supervisorctl status | while read -r line; do
    echo "$line" | grep -q "RUNNING" || continue

    name=$(echo "$line" | awk '{print $1}')
    pid=$(echo "$line" | grep -oP 'pid \K[0-9]+')

    [[ -z "$pid" ]] && continue

    cwd=$(readlink "/proc/$pid/cwd" 2>/dev/null)

    if [[ "$cwd" == "$TARGET_DIR"* ]]; then
        echo "Restarting $name (pid $pid, dir $cwd)"
        supervisorctl restart "$name"
    fi
done

How it works

supervisorctl status lists all daemons with their current PIDs.
Non-RUNNING daemons are skipped (they have no PID to look up).
/proc//cwd resolves the actual working directory for each process.
Any daemon whose working directory matches the target path (or is a subpath of the target path) gets restarted.

Usage

chmod +x restart-daemons.sh
./restart-daemons.sh /home/forge/my-app/current

This is especially useful on servers running multiple deployments of the same application — for example, a staging environment with both a current and a previous release still running workers.

#laravel #devops #terminal #linux #sysadmin

🐥 Make your shell scripts' environment variables overridable

2026-05-09T17:00:00Z

When writing shell scripts, hardcoded values are a common source of friction. A script that works perfectly on your machine may need adjustments on a colleague's setup, in CI, or in production — and forcing people to edit the script itself is messy.

There's a simple Bash idiom that solves this cleanly.

The Problem

Consider a typical startup script:

PORT=8888
HOST=0.0.0.0

uvicorn myapp:app --host $HOST --port $PORT

The port is hardcoded. If you need to run two instances, or if 8888 is already taken, you have to edit the file.

The Fix: `${VAR:-default}`

Replace the hardcoded assignment with a default-value expansion:

PORT=${PORT:-8888}
HOST=${HOST:-0.0.0.0}

uvicorn myapp:app --host $HOST --port $PORT

The syntax ${VAR:-default} means:

Use the value of $VAR if it is set and non-empty; otherwise use default.

The script's behaviour is unchanged when no environment variable is provided — the default kicks in. But now callers can override it without touching the file:

PORT=9000 ./bin/start.sh

Or by exporting it beforehand:

export PORT=9000
./bin/start.sh

Why This Matters

No edits required. The script stays clean; overrides happen at call time.
CI-friendly. Most CI systems let you set environment variables per job. Your script picks them up automatically.
Self-documenting. The default value lives right next to the variable name, so readers immediately know what to expect.
Composable. You can layer overrides: a .env file, a CI variable, or a one-liner prefix — whatever fits the context.

Variants Worth Knowing

Syntax	Meaning
`${VAR:-default}`	Use `default` if `VAR` is unset or empty
`${VAR-default}`	Use `default` only if `VAR` is unset (empty string is kept)
`${VAR:=default}`	Use `default` and assign it back to `VAR` if unset or empty
`${VAR:?message}`	Abort with `message` if `VAR` is unset or empty

For most cases, ${VAR:-default} is the right choice. The := variant is useful when you want the variable available for the rest of the script without repeating the default.

A Real-World Example

Here's a before/after for a uvicorn startup script:

Before:

HOST=0.0.0.0
PORT=8888

uvicorn docai.api.app:app --host $HOST --port $PORT

After:

HOST=${HOST:-0.0.0.0}
PORT=${PORT:-8888}

uvicorn docai.api.app:app --host $HOST --port $PORT

Two characters added per line (${ and :-), zero behaviour change by default, and now fully overridable from the outside. A small habit with outsized payoff.

#best-practice #devops #terminal

🐥 Using generators for PHPUnit data providers

2026-05-07T17:00:00Z

When writing PHPUnit tests, data providers are one of the simplest ways to increase coverage without duplicating test logic. Most examples use arrays, but PHP generators (yield) are often a better fit: they’re more expressive, memory-efficient, and easier to extend.

This post walks through a clean, generic approach to using generators for PHPUnit data providers.

Why use generators instead of arrays?

A traditional data provider might look like this:


public static function provideCases(): array
{
    return [
        'case A' => ['input-a', 'expected-a'],
        'case B' => ['input-b', 'expected-b'],
    ];
}

This works, but generators give you a few advantages:

No need to build a full array in memory
Named cases are more natural with yield
Easier to compose or split into smaller logical chunks
Better readability when cases grow

A simple example

Imagine you’re testing a service that transforms input values:


final class ValueTransformer
{
    public function transform(string $value): string
    {
        return strtoupper($value);
    }
}

Instead of writing multiple test methods, you can use a generator-based data provider:


use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\Attributes\Test;

final class ValueTransformerTest extends TestCase
{
    #[Test]
    #[DataProvider('provideTransformCases')]
    public function it_transforms_values(string $input, string $expected): void
    {
        $service = new ValueTransformer();

        $result = $service->transform($input);

        $this->assertSame($expected, $result);
    }

    public static function provideTransformCases(): \Generator
    {
        yield 'lowercase' => ['hello', 'HELLO'];
        yield 'mixed case' => ['HeLLo', 'HELLO'];
        yield 'already uppercase' => ['WORLD', 'WORLD'];
    }
}

Making test cases more expressive

Generators really shine when your inputs are objects instead of primitives.

For example, testing a query modifier:


final class QueryModifier
{
    public function apply(QueryBuilder $query, string $field, string $direction): QueryBuilder
    {
        return $query->orderBy($field, $direction);
    }
}

Your test can focus on behavior while the generator defines the variations:


#[Test]
#[DataProvider('provideSortingCases')]
public function it_applies_sorting(string $field, string $direction): void
{
    $query = Mockery::mock(QueryBuilder::class);
    $query->shouldReceive('orderBy')
        ->once()
        ->with($field, $direction)
        ->andReturnSelf();

    $modifier = new QueryModifier();

    $modifier->apply($query, $field, $direction);
}

public static function provideSortingCases(): \Generator
{
    yield 'sort by name' => ['name', 'asc'];
    yield 'sort by created_at desc' => ['created_at', 'desc'];
    yield 'sort by nested field' => ['user.email', 'asc'];
}

The test stays minimal, while the generator clearly documents the supported scenarios.

Composing generators

One underrated benefit is that generators can be composed. You can split cases into smaller methods and reuse them:


public static function provideSortingCases(): \Generator
{
    yield from self::basicFields();
    yield from self::nestedFields();
}

private static function basicFields(): \Generator
{
    yield 'name asc' => ['name', 'asc'];
    yield 'created_at desc' => ['created_at', 'desc'];
}

private static function nestedFields(): \Generator
{
    yield 'user email' => ['user.email', 'asc'];
}

This keeps large test suites maintainable without sacrificing clarity.

When to prefer generators

Generators are especially useful when:

You have many test cases
Test data is constructed dynamically
You want to group or reuse subsets of cases
Memory usage might become a concern

For small, static datasets, arrays are perfectly fine. But once your data providers grow, generators tend to scale much better.

Final thoughts

Using generators in PHPUnit data providers is a small change that improves readability and flexibility. Tests become easier to extend, and the intent of each case is clearer thanks to named yields.

If you’re already relying on data providers, switching from arrays to generators is a low-effort improvement that pays off quickly in larger test suites.

#php #best-practice #testing

🐥 Fixing the Ondrej Nginx PPA 403 error on Laravel Forge servers

2026-05-05T17:00:00Z

If you're running Ubuntu 22.04 on a Laravel Forge-managed server, you may have recently started seeing this error during apt update:

Err:7 https://ppa.launchpadcontent.net/ondrej/nginx/ubuntu jammy InRelease
  403  Forbidden
E: The repository 'https://ppa.launchpadcontent.net/ondrej/nginx/ubuntu jammy InRelease' is no longer signed.

What's happening?

Forge historically added the ondrej/nginx PPA to its servers to get newer versions of nginx. Ondrej Surý (the maintainer) has since moved this PPA to a paid subscription model, so unauthenticated access now returns a 403. Your server still has the old PPA entry, but it can no longer reach it.

You'll notice the ondrej/php PPA still works fine — that one remains freely available.

The fix

Step 1: Find the file that references the broken PPA:

grep -r "ondrej/nginx" /etc/apt/sources.list.d/

Step 2: Remove it (the filename will match what grep returned above):

sudo rm /etc/apt/sources.list.d/ondrej-ubuntu-nginx-jammy.list
sudo rm -f /etc/apt/sources.list.d/ondrej-ubuntu-nginx-jammy.list.distUpgrade

Note: add-apt-repository --remove ppa:ondrej/nginx won't work here — Launchpad returns a 403 before it can resolve the PPA name.

Step 3: Run apt update again. If you need a newer version of nginx than Ubuntu's default (1.18.x), add the official nginx.org repository instead:

curl -fsSL https://nginx.org/keys/nginx_signing.key | sudo gpg --dearmor -o /usr/share/keyrings/nginx-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] http://nginx.org/packages/ubuntu jammy nginx" \
  | sudo tee /etc/apt/sources.list.d/nginx.list

sudo apt update
sudo apt install nginx

Do you need a newer nginx?

For most Laravel applications, Ubuntu's default nginx is perfectly adequate. Unless you have a specific reason to run a cutting-edge nginx version, removing the PPA and sticking with the default is the simplest and most stable path.

#laravel #best-practice #devops #linux #sysadmin

🐥 Upgrading firebase/php-jwt to v7 in a Laravel App (transitive dependency trap)

2026-04-24T17:00:00Z

A few weeks ago we upgraded firebase/php-jwt from v6 to v7 in our app. It sounds like a routine dependency bump — update the version constraint in composer.json, run composer update, done. But there was a catch: one of our other packages, socialiteproviders/microsoft, had a hard constraint on the old version. This is the classic transitive dependency conflict, and if you haven't run into it before, you will.

Here's how we handled it and how you should too.

What's a transitive dependency conflict?

Your composer.json only lists the packages you directly depend on. But each of those packages has its own composer.json, listing their dependencies — and those packages have their own, and so on. This tree is your full dependency graph.

A transitive dependency conflict happens when you want to upgrade Package A, but Package B — which you also require — has a hard constraint that prevents it from working with the new version of A.

In our case:

We wanted: firebase/php-jwt: ^7.0
socialiteproviders/microsoft (v4.7.1) declared: "firebase/php-jwt": "^6.8"

These two constraints are mutually exclusive. Composer can't install a version of firebase/php-jwt that satisfies both ^7.0 and ^6.8 simultaneously, so it would refuse — with a dependency resolution error.

Step 1: Understand the dependency graph before touching anything

The first move is to inspect what the problematic package actually requires:

composer show socialiteproviders/microsoft

This outputs the requires section:

requires
php ^8.0
ext-json *
firebase/php-jwt ^6.8
socialiteproviders/manager ^4.4

There it is. Before writing a single line, you know exactly what needs to change.

Step 2: Validate with a dry run

Rather than guessing whether a combination of versions will resolve, ask Composer directly using --dry-run:

composer require --dry-run "firebase/php-jwt:^7.0" "socialiteproviders/microsoft:^4.9"

Composer will either:

Print a clean resolution plan with the exact versions it would install, or
Print an error telling you exactly which package is blocking and why

In our case it resolved cleanly:

Lock file operations: 0 installs, 3 updates, 0 removals
  - Upgrading firebase/php-jwt (6.x-dev => v7.0.5)
  - Upgrading socialiteproviders/microsoft (4.7.1 => 4.9.1)

Nothing was written to disk. We just confirmed the upgrade path works.

Step 3: Update both packages in a single command

This is the part people get wrong. If you only update firebase/php-jwt:

# ❌ This will fail — socialiteproviders/microsoft still requires ^6.8
composer update firebase/php-jwt

Composer will refuse because the new firebase/php-jwt v7 conflicts with the installed socialiteproviders/microsoft v4.7.1. You must update both in one pass so Composer can solve the graph holistically:

# ✅ Composer solves both constraints together
composer update firebase/php-jwt socialiteproviders/microsoft

Output:

- Upgrading firebase/php-jwt (6.x-dev => v7.0.5): Extracting archive
- Upgrading socialiteproviders/microsoft (4.7.1 => 4.9.1): Extracting archive
No security vulnerability advisories found.

Step 4: Bump the constraint in composer.json

Don't forget to update your version constraints in composer.json to reflect the new minimums:

"firebase/php-jwt": "^7.0",
"socialiteproviders/microsoft": "^4.9",

Why ^4.9 instead of leaving it at ^4.1? Because ^4.9 documents intent: "we need at least 4.9, because that's the version that supports firebase/php-jwt v7." If you leave it at ^4.1, a future composer update could theoretically resolve back to 4.7.x in some edge case and silently reintroduce the conflict.

Step 5: Check your own code for API breakage

A major version bump means potential breaking changes. Grep for every place you use the package:

grep -r "Firebase\\JWT" app/ --include="*.php" -l

For firebase/php-jwt specifically, JWT::encode() kept the same signature in v7 — the only notable change was a stricter PHP type hint on the $key parameter (OpenSSLAsymmetricKey|OpenSSLCertificate|string vs the old loosely-typed $key). Since we pass strings (shared secrets and RSA private keys), there was nothing to change in our ZendeskJwtTokenBuilder or DocuSignJwtTokenBuilder.

Step 6: Run the affected tests

XDEBUG_MODE=off php artisan test --compact \
  tests/Unit/Domains/Tokens/JwtTokenBuilderTest.php \
  tests/Feature/Authentication/MicrosoftLoginTest.php

Tests:    27 passed (106 assertions)
Duration: 10.44s

Green. Ship it.

The general playbook

Whenever you hit a transitive dependency conflict in Composer:

Step	What to do
1	`composer show` — find the conflicting constraint
2	`composer require --dry-run "a:^X" "b:^Y"` — validate resolution without touching files
3	`composer update a b` — update all conflicting packages in one pass
4	Tighten the version constraint in `composer.json` to document the new minimum
5	Grep for usages, read the changelog for breaking API changes
6	Run the affected tests

The core insight: Composer's constraint solver needs to see the full picture. If you update one package at a time when there's a conflict, you're fighting the solver instead of working with it.

#development #laravel #php #best-practice

🐥 Installing Claude Code on macOS with Homebrew (and getting the latest version)

2026-04-02T17:00:00Z

If you’re installing Claude Code on macOS using Homebrew, the official instruction currently suggests:

brew install claude-code

While this works, it installs the latest stable version, not the latest available version. Depending on your use case, that can leave you behind on features and fixes.

Install the latest version

To install the most recent release, you should explicitly use:

brew install claude-code@latest

This ensures you’re running the newest version instead of the lagging stable cask.

Fix an existing installation

If you already installed claude-code using the default command, you’ll need to replace it:

brew uninstall claude-code && brew install claude-code@latest

That removes the stable version and installs the latest one cleanly.

Why this matters

Homebrew distinguishes between:

Stable casks → default installs (claude-code)
Versioned or alternative casks → explicit installs (claude-code@latest)

In this case, the naming is a bit misleading because @latest is not the default. This has already caused confusion in the community and is being discussed upstream.

More context

Issue discussion: https://github.com/anthropics/claude-code/issues/42176
Homebrew PR: https://github.com/Homebrew/homebrew-cask/pull/255221

Takeaway

If you want the newest Claude Code features and fixes, don’t rely on the default install. Use:

brew install claude-code@latest

and you’ll avoid running an outdated version without realizing it.

#tools #announcement #mac

🐥 YellowDuck.be

🐥 The MySQL null-safe equality operator: <=>

The problem with = and NULL

Enter <=>

A real-world example

<=> vs. the alternatives

When to use it

Caveats

Summary

🐥 Testing that Laravel events fire after a transaction commits

The problem

The test pattern

Why compare against $baselineLevel instead of 0?

Handling listener cascades

1. Fake only the cascading action

2. Fake only the jobs

Checking multiple events

Quick reference

🐥 Speeding up S3 uploads in GitHub Actions with Bash parallelism

The problem

The fix

How it works

Why not just wait?

The general pattern

🐥 Debugging PHPUnit notices in Laravel parallel tests

The command

What each part does

Environment variables

Invoking paratest directly

Surfacing notices

Scoping to tests/Unit

Reading the output

Making it a habit

🐥 From N+1 to 1: Extracting paged PDF text with a single pdftotext call

The problem: N+1 process spawns

The insight: pdftotext already separates pages

The solution

Edge cases worth knowing

The broader pattern

🐥 The silent saboteur: how --quiet can break your Laravel command sequences

The setup

The problem

Why it happens

The fix

The lesson

Bonus: write the test first

🐥 How to check how much memory a systemd unit is actually using

Using systemctl

Using systemctl show

Inspecting the cgroup directly

Finding the processes behind a service

Monitoring memory usage over time

Configuring memory limits

Conclusion

🐥 Fixing PHPUnit 13 with*() without expects() deprecations in Laravel tests

The real issue

The fix

Why this works

Final result

🐥 Why crypto.getRandomValues() matters in JavaScript

The problem with Math.random()

Using crypto.getRandomValues()

Generating a secure random token

Typed arrays are required

Browser and runtime support

UUID generation

Things to remember

🐥 How to find all Jira issues ever assigned to someone (even historical ones)

The was operator

Checking multiple people at once

Scoping to a specific year

Putting it all together

🐥 Downloading external images as squares from a Phoenix app

The CORS problem

The fix: a server-side proxy

Center-cropping to a square in the browser

Wiring it up in LiveView

Why naturalWidth instead of width?

🐥 The Tailwind `enabled:` selector trick for disabled buttons

The problem

The problem with `=` and `NULL`

Enter `<=>`

`<=>` vs. the alternatives

Why compare against `$baselineLevel` instead of `0`?

Why not just `wait`?

Scoping to `tests/Unit`

The problem with `Math.random()`

Using `crypto.getRandomValues()`

The `was` operator

Why `naturalWidth` instead of `width`?

The fix: `enabled:`

What Is `Pick`?

`Pick` vs `Omit`

The Fix: `${VAR:-default}`