DEV Community: Jerome Thayananthajothy

Introducing Honeymelon: A Case Study in Building a Better Media Converter

Jerome Thayananthajothy — Fri, 06 Feb 2026 05:50:22 +0000

The Problem That Started It All

A few years ago I found myself doing the same thing over and over: converting video and audio files on my Mac so they would play nicely in editors, browsers, or on devices that refused to cooperate with whatever codec I had thrown at them. I was tired of hunting for the right ffmpeg flags every time, so I did what any developer would do - I built a desktop app to handle it for me.

That first version was an Electron app. It worked. It solved my problem. But it also consumed an unreasonable amount of memory, shipped a bloated binary, and felt sluggish on a machine that should have breezed through simple media tasks. Every time I opened it I winced at the Activity Monitor numbers. Something had to change.

Honeymelon is that change.

What Honeymelon Actually Is

Honeymelon is a free, open-source media converter built exclusively for macOS on Apple Silicon. It wraps FFmpeg in a clean, native interface and makes one bet that pays off more often than you would expect: most conversions do not need re-encoding at all.

The core idea is called "remux-first." Before Honeymelon touches a single frame it probes your file, checks whether the existing streams are already compatible with the target container, and — if they are — simply repackages them without decoding or encoding. The result is a conversion that finishes in seconds instead of minutes, with zero quality loss.

When transcoding is genuinely required, Honeymelon leans on Apple VideoToolbox for hardware-accelerated H.264, HEVC, and ProRes encoding, and offers three quality tiers — Fast, Balanced, and High — so you can decide where you want to land on the speed-versus-quality spectrum.

Everything happens locally. There is no telemetry, no network traffic, no account to create. You drag files in, pick a preset, and get your output.

Why I Rebuilt From Scratch

The Electron version taught me two things. First, wrapping a full Chromium browser inside a desktop app carries a cost that is hard to justify for a utility that should feel lightweight. Second, user experience matters as much as functionality - if the tool feels heavy, people stop reaching for it even when it works.

I chose Tauri 2 with a Vue 3 frontend and a Rust backend for the rewrite. The difference was immediate:

Application size dropped dramatically. The distributed DMG is a fraction of what the Electron build weighed.
Memory usage fell to levels you would expect from a native macOS utility rather than a web browser pretending to be one.
Startup time became nearly instant. The Rust backend initializes FFmpeg capability detection in the background while the UI renders.
Responsiveness improved across the board. Tauri's IPC layer and Rust's async runtime handle concurrent FFmpeg processes without the overhead of a Node.js event loop marshalling everything through a single thread.

Choosing Rust for the backend was not just about performance. It brought real safety guarantees — no null pointer panics crashing your conversion mid-job, proper error propagation through typed Result values, and memory safety without a garbage collector pause interrupting progress events.

The Architecture: Probe, Plan, Execute

Under the hood, every conversion passes through three stages.

Stage 1 — Probe

Honeymelon invokes ffprobe to extract detailed metadata from the input file: codecs, container format, duration, resolution, frame rate, color primaries, transfer characteristics, and subtitle types. This data feeds directly into the planning stage.

Stage 2 — Plan

A pure TypeScript planning engine evaluates the probe results against the selected preset. It checks container compatibility rules - for example, MP4 only supports certain video and audio codecs - and decides stream by stream whether to copy or transcode. The planner emits a complete set of FFmpeg arguments and a human-readable summary of what it intends to do, along with any warnings.

The planning logic lives entirely on the frontend, which means it can run instantly without a round-trip to the Rust backend. You see the decision before you commit to it.

Stage 3 — Execute

The Rust backend spawns FFmpeg as a child process, parses its stderr output for progress metrics in a dedicated thread, and streams real-time updates - time processed, frames per second, encoding speed, estimated time remaining - back to the Vue UI through Tauri events.

Concurrency is managed carefully. You can run multiple jobs in parallel, but resource-intensive codecs like AV1 and ProRes automatically trigger exclusive mode, preventing other heavy jobs from starting until they complete. Output files are written to a temporary path first and atomically renamed on success, so a crash or cancellation never leaves behind a half-written file.

A Case Study in Trade-Offs

Building Honeymelon meant making deliberate trade-offs, and I think the decisions are worth examining.

Platform scope

Honeymelon targets macOS on Apple Silicon exclusively. No Windows, no Linux, no Intel Macs. This is a genuine constraint, and I understand it limits the audience. But it also means the app can lean fully into VideoToolbox hardware acceleration, declare native ARM64 architecture in its bundle metadata, and avoid the cross-platform compromises that dilute so many desktop tools. The result is an application that feels like it belongs on your Mac because it was built for nothing else.

LGPL compliance through process separation

FFmpeg is licensed under the LGPL. Rather than linking against its libraries — which would impose LGPL obligations on Honeymelon's own code — the app runs FFmpeg as a completely separate process. Communication happens exclusively through command-line arguments, standard streams, and the file system. No shared memory, no dynamic linking, no library calls. This keeps the licensing clean and lets Honeymelon ship under the GPL v3 without conflict.

Privacy as a default

There is no analytics SDK, no crash reporter phoning home, no update check pinging a server. I built this for myself first, and I do not want my media converter talking to the internet. That philosophy extends to every user. If you are working with sensitive footage or operating in an air-gapped environment, Honeymelon will never surprise you with an outbound connection.

Free software, full stop

Honeymelon is licensed under the GNU General Public License v3.0 or later. It is not "free tier with upsells." It is not "open core with a proprietary edition." It is free software in the fullest sense — free to use, free to study, free to modify, free to distribute.

I built this app to solve my own problem. Once it was working, the only honest thing to do was share it. Media conversion is a universal need. Charging for a wrapper around FFmpeg never sat right with me. I believe tools like this should benefit everyone, and profit was never the goal.

What I Learned

If there is a single takeaway from this project, it is this: the tools you choose determine the experience you can deliver.

Electron gave me rapid iteration and a familiar web stack, but it imposed a floor on resource consumption that no amount of optimization could lower. Tauri and Rust removed that floor. The same features — concurrent job management, real-time progress tracking, subtitle handling, color metadata preservation — now run in a package that feels native because it is native.

The second lesson is that simplicity is a feature. The remux-first strategy is not technically impressive. It is a straightforward check: does the source codec match the target? If yes, copy the stream. But that simple check saves users enormous amounts of time and preserves quality they would otherwise lose to unnecessary transcoding. The best engineering often looks obvious in retrospect.

The third lesson is personal. Building for yourself is a legitimate motivation. Not every project needs a market analysis or a competitive landscape. Sometimes you just need a tool that does one thing well and does not waste your time or your machine's resources doing it. If other people find it useful, that is a bonus — but the software justifies itself the moment it solves your problem.

Getting Started

Honeymelon is available now on GitHub under the GPL v3.

Repository: github.com/honeymelon-app/honeymelon
Download: Grab the latest signed DMG from the Releases page
Requirements: macOS 13 or later on Apple Silicon (M1, M2, M3, M4)

To build from source:

git clone https://github.com/honeymelon-app/honeymelon.git
cd honeymelon
npm install
npm run tauri dev

Contributions are welcome. Whether it is a bug report, a new preset, a documentation fix, or a feature idea - the project is open and the issue tracker is waiting.

Final Thoughts

Honeymelon exists because I needed it. It is free because I believe it should be. And it is open source because the best tools get better when other people can see how they work, point out where they fall short, and help make them stronger.

If you convert media files on a Mac, give it a try. If you are a developer curious about Tauri, Rust, or Vue 3, dig into the source. And if you have feedback, I would genuinely like to hear it.

Building Altus 4: Why I Created an AI-Enhanced MySQL Search Engine (Instead of Just Using Elasticsearch)

Jerome Thayananthajothy — Thu, 04 Sep 2025 16:27:43 +0000

A case study in solving the "search problem" without forcing infrastructure migrations

The Problem That Started It All

Picture this: You're three months into building a SaaS application. Your users love it, but they keep asking for one thing; better search functionality. Your current MySQL LIKE queries are slow, inflexible, and frankly embarrassing when users type "find my recent premium orders" and get zero results.

Sound familiar? This exact scenario has played out in every project I've worked on. The usual advice? "Just migrate to Elasticsearch." But that always felt like using a sledgehammer to crack a nut.

So I built Altus 4, an AI-enhanced MySQL full-text search engine that works with your existing database infrastructure.

Why Not Just Use Elasticsearch?

Don't get me wrong; Elasticsearch is incredible. But for most applications, it introduces unnecessary complexity:

The Elasticsearch Route:

New infrastructure to provision, configure, and maintain
Data synchronization nightmares between MySQL and ES
Learning curve for your entire team
Operational overhead of managing two data stores
Additional costs for hosting and maintenance

The Reality Check:

Most applications don't need the full power of Elasticsearch. They just need MySQL to be smarter about search.

Enter Altus 4: Enhancing MySQL Instead of Replacing It

The core insight behind Altus 4 is simple: What if we could make MySQL's existing full-text search intelligent without changing your data architecture?

Here's what that looks like in practice:

Before (Traditional MySQL Search):

SELECT * FROM products 
WHERE name LIKE '%premium coffee%' 
OR description LIKE '%premium coffee%';

After (Altus 4 Enhanced):

curl -X POST http://localhost:3000/api/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "query": "find premium coffee products",
    "databases": ["ecommerce_db"],
    "searchMode": "natural"
  }'

The difference? Altus 4 understands that "premium coffee products" should also match "high-quality espresso beans" or "artisan coffee roasters" thanks to AI-powered semantic understanding.

Technical Architecture: How It Works

Altus 4 sits between your application and MySQL databases, enhancing search capabilities through several layers:

Core Components:

1. Database Service Layer

Connects to multiple MySQL databases
Discovers existing full-text indexes
Manages connection pooling and optimization

2. AI Enhancement Layer

OpenAI integration for semantic search
Query optimization and natural language processing
Relevance scoring improvements

3. Search Orchestration

Federated search across multiple databases
Result ranking and deduplication
Real-time analytics and caching

The Magic: Semantic Search Implementation

Here's a simplified version of how the semantic enhancement works:

class SearchService {
  async enhancedSearch(query: string, databases: string[]) {
    // 1. Generate embeddings for the search query
    const queryEmbedding = await this.aiService.generateEmbedding(query);

    // 2. Execute traditional full-text search
    const traditionalResults = await this.executeFullTextSearch(query, databases);

    // 3. Enhance with semantic understanding
    const semanticResults = await this.findSemanticMatches(queryEmbedding, databases);

    // 4. Combine and rank results
    return this.rankAndCombineResults(traditionalResults, semanticResults);
  }

  private async findSemanticMatches(embedding: number[], databases: string[]) {
    // Find conceptually similar content even without exact keyword matches
    return this.vectorSimilaritySearch(embedding, databases);
  }
}

Real-World Use Case: E-commerce Search

Let me show you a concrete example. I implemented Altus 4 for a client's e-commerce platform:

The Challenge:

50,000+ products across multiple categories
Users searching with natural language ("gifts for coffee lovers")
Existing MySQL setup they didn't want to change
Need for real-time inventory integration

The Implementation:

1. Setup (literally 5 minutes):

git clone https://github.com/altus4/core.git
cd altus4
npm install
cp .env.example .env
# Configure MySQL and OpenAI credentials
npm run migrate
npm run dev

2. Connect existing database:

curl -X POST http://localhost:3000/api/v1/databases \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "E-commerce DB",
    "host": "localhost",
    "database": "ecommerce",
    "username": "db_user",
    "password": "password"
  }'

3. Start searching:

// Natural language search
const results = await fetch('/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: "gifts for coffee enthusiasts under $50",
    databases: ["ecommerce_db"],
    searchMode: "natural",
    filters: {
      price: { max: 50 }
    }
  })
}).then(r => r.json());

The Results:

Search relevance improved by 60% (measured by click-through rates)
Setup time: 30 minutes vs. weeks for Elasticsearch migration
Zero downtime during implementation
Maintenance overhead: minimal (just keeping Altus 4 updated)

Comparison: Altus 4 vs. Traditional Approaches

Feature	MySQL LIKE	Elasticsearch	Altus 4
Setup Time	5 minutes	2-4 weeks	30 minutes
Infrastructure Changes	None	Significant	None
Semantic Search	❌	✅	✅
Natural Language	❌	✅	✅
Operational Complexity	Low	High	Low
Multi-Database Search	Manual	Complex	Built-in
Cost (monthly)	$0	$500-2000+	$50-200

Getting Started: Your First Search in 10 Minutes

Want to try this out? Here's a complete walkthrough:

Prerequisites:

Node.js 18+
MySQL 8.0+
Redis 6.0+
OpenAI API key (optional for basic features)

Step 1: Installation

git clone https://github.com/altus4/core.git
cd altus4
npm install

Step 2: Environment Setup

cp .env.example .env

Edit .env with your credentials:

DB_HOST=localhost
DB_USERNAME=your_mysql_user
DB_PASSWORD=your_mysql_password
DB_DATABASE=altus4_metadata

REDIS_HOST=localhost
REDIS_PORT=6379

OPENAI_API_KEY=sk-your-openai-key

Step 3: Database Setup

# Run migrations to create Altus 4 metadata tables
npm run migrate

# Start the server
npm run dev

Step 4: Add Your First Database

curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "secure_password",
    "name": "Test User"
  }'

# Follow the authentication flow to get your API key
# Then add your database connection

Step 5: Your First Search

const searchResponse = await fetch('/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: "user accounts created last month",
    databases: ["your_db_id"],
    searchMode: "natural"
  })
});

const results = await searchResponse.json();
console.log(results);

When Should You Use Altus 4?

Altus 4 is perfect for:

Great Fit:

Existing MySQL applications needing better search
Teams wanting to avoid Elasticsearch complexity
SaaS applications with user-generated content
E-commerce platforms with product catalogs
Internal tools and admin dashboards
Prototypes and MVPs needing professional search quickly

Consider Alternatives:

Massive scale (millions of searches per second)
Complex aggregation requirements beyond search
Teams already invested in Elasticsearch ecosystem
Applications requiring millisecond response times at scale

Technical Deep-Dive: Architecture Decisions

Why TypeScript?

Type safety was crucial for this project. With multiple database connections, AI integrations, and complex search logic, TypeScript caught countless potential runtime errors during development.

Why Express.js?

Familiarity and ecosystem. Most developers know Express, and the middleware ecosystem is unmatched for authentication, validation, and logging.

Why MySQL for Metadata?

Dogfooding our own solution. Altus 4's own metadata (user accounts, API keys, database connections) is stored in MySQL and searchable through the same API.

Why Redis?

Two main use cases:

Caching search results for performance
Storing search analytics and user behavior data

Challenges and Lessons Learned

Challenge 1: Connection Pool Management

Managing connections to multiple MySQL databases efficiently required custom pooling logic:

class DatabaseConnectionManager {
  private pools = new Map<string, mysql.Pool>();

  async getConnection(databaseId: string): Promise<mysql.PoolConnection> {
    if (!this.pools.has(databaseId)) {
      const config = await this.getDatabaseConfig(databaseId);
      this.pools.set(databaseId, mysql.createPool(config));
    }

    return this.pools.get(databaseId)!.getConnection();
  }
}

Challenge 2: AI Rate Limiting

OpenAI has rate limits. For semantic search, we implemented intelligent batching:

class AIService {
  private requestQueue: QueryQueue = new QueryQueue();

  async generateEmbedding(text: string): Promise<number[]> {
    // Batch multiple requests and respect rate limits
    return this.requestQueue.add(async () => {
      return this.openai.createEmbedding({
        model: "text-embedding-ada-002",
        input: text
      });
    });
  }
}

Challenge 3: Result Ranking

Combining traditional full-text scores with semantic similarity scores required experimentation:

private calculateCombinedScore(
  fullTextScore: number,
  semanticScore: number,
  boost: number = 1.0
): number {
  // Weighted combination with configurable boost
  return (fullTextScore * 0.7 + semanticScore * 0.3) * boost;
}

What's Next: Roadmap

I'm actively developing Altus 4 with these priorities:

Short-term (Next 3 months):

Vector database integration for better semantic search performance
GraphQL API alongside REST
Webhook support for real-time search index updates
Advanced analytics dashboard

Long-term (6+ months):

Auto-scaling capabilities for high-traffic applications
Machine learning for personalized search ranking
Multi-language support beyond English
Plugin ecosystem for custom search behaviors

Open Source and Community

Altus 4 is completely open source (Apache 2.0 License). I built this to solve a real problem I kept encountering, and I'm excited to see how the community uses and improves it.

Contributing:

GitHub: [Repository link]
Issues: Bug reports and feature requests welcome
Pull Requests: All skill levels welcome
Documentation: Always needs improvement

Community:

Discord: Join our developer community
Examples: Real-world implementation examples
Blog: Regular technical deep-dives

Conclusion: Solving Real Problems

Building Altus 4 taught me that sometimes the best solution isn't the most obvious one. Instead of joining the "just use Elasticsearch" chorus, I asked: "What if we made MySQL smarter instead?"

The result is a tool that:

Solves the search problem for 80% of applications
Respects existing architecture decisions
Reduces operational complexity instead of adding to it
Provides enterprise features without enterprise overhead

If you're struggling with search in your MySQL-based application, give Altus 4 a try. It might just be the "good enough" solution that's actually better than the complicated alternative.

Try Altus 4:

Website: https://altus4.thavarshan.com
GitHub: https://github.com/altus4/core
Documentation: https://altus4.thavarshan.com/docs

Tags: #mysql #opensourcedev #ai #searchengine #typescript #nodejs #elasticsearch

Wisp a Modern, Secure One-Time Secret Sharing App Built with Laravel 12, Vue 3 and Inertia.

Jerome Thayananthajothy — Fri, 15 Aug 2025 01:13:07 +0000

In a world where sensitive data leaks happen daily, sharing passwords, API keys, or confidential information over email or chat is risky.
We’ve all been there — “Can you send me the database password?” and before you know it, it’s stored permanently in Slack history or someone’s inbox.

That’s the problem Wisp solves.

The Solution: Wisp

Wisp is a secure, one-time secret sharing application.
It allows you to send encrypted secrets via unique links that expire after being viewed or after a set period of time, after which they are permanently deleted.

Key highlights:

Secrets are encrypted using AES-256-CBC before storage
Optional password protection
Links auto-expire after minutes, hours, or days
Secrets are deleted permanently after first viewing
No decrypted secret is ever stored server-side

Technical Deep-Dive

Wisp is built with a stack that prioritizes security, developer productivity, and a modern user experience.

Backend

Laravel 12.21 with PHP 8.4
Laravel’s AES-256-CBC encryption
Bcrypt password hashing
MySQL 8.0+
PHPUnit for backend tests

Frontend

Vue 3.5 (Composition API) with TypeScript
Inertia.js 2.0 for seamless Laravel-Vue integration
Tailwind CSS 3.4 with shadcn/ui for consistent UI components
Ziggy for Laravel routes in JavaScript

Hosting

Deployed on Heroku with HTTPS enforced

Security Implementation

Wisp’s core principle: encrypt sensitive data immediately, destroy it quickly, and never store it in plain text.

How it works:

Secrets are encrypted with AES-256-CBC before saving to the database.
If a password is set, it is hashed using Bcrypt and verified before decryption.
On first view, the secret is permanently deleted.
If not viewed, it is automatically removed at the set expiration time.

// Laravel encryption example
$encrypted = encrypt($secretContent);
$decrypted = decrypt($encrypted);

Why Inertia.js?

Instead of building a traditional API with a separate frontend, Wisp uses Inertia.js to connect Laravel and Vue directly.

Benefits:

No need for API controllers or serialization layers
Laravel handles routing and authentication natively
SPA experience without managing a separate API stack

Example Inertia route in Laravel:

Route::get('/secrets/create', function () {
    return Inertia::render('Secrets/Create');
})->name('secrets.create');

Developer Experience

Laravel Pint for automatic code formatting
Nightwatch.js for end-to-end testing of the secret sharing flow
Full TypeScript support for frontend predictability
shadcn/ui for accessible and reusable components

Installation

Clone the repository:

git clone https://github.com/Thavarshan/wisp.git
cd wisp

Install dependencies:

composer install
npm install

Configure environment:

cp .env.example .env
php artisan key:generate

Run migrations:

php artisan migrate

Start the application:

php artisan serve
npm run dev

Usage

Visit / and create a new secret
Set an optional password and expiration time
Share the generated link
Once opened, the secret is permanently deleted

Contributing

Wisp is open-source and welcomes contributions.

GitHub: https://github.com/Thavarshan/wisp
Issues and pull requests are encouraged
Feedback is always welcome

Call to Action

If you’ve ever sent a password over chat and worried about where it might end up, Wisp is for you.
Try it out, give it a star on GitHub, and help improve it. Together, we can make secure sharing the default.

Introducing Filterable: A Powerful, Modular Query Filtering System for Laravel

Jerome Thayananthajothy — Tue, 13 May 2025 19:18:51 +0000

If you've built Laravel applications that require complex filtering of your Eloquent models, you've likely faced the challenge of keeping your controller code clean while implementing robust query filters. Today, I'm excited to introduce Filterable, a new open-source package that makes dynamic query filtering both powerful and simple with its modular, trait-based architecture.

The Problem: Messy Controller Code

We've all been there. Your controller starts simple, but as filtering requirements grow, it quickly becomes cluttered:

public function index(Request $request)
{
    $query = Post::query();

    if ($request->has('status')) {
        $query->where('status', $request->status);
    }

    if ($request->has('category')) {
        $query->where('category_id', $request->category);
    }

    if ($request->has('search')) {
        $query->where('title', 'like', "%{$request->search}%");
    }

    // More conditional filters...

    return $query->paginate();
}

As your application grows, this approach leads to bloated controllers, duplicated code, and difficult-to-maintain filter logic. That's where Filterable comes in.

The Solution: Filterable

Filterable provides a clean, modular approach to filter your Laravel Eloquent queries based on request parameters. But it doesn't stop there - it offers a rich set of features through its trait-based architecture, allowing you to pick and choose functionality based on your needs.

Key Features

Dynamic Filtering: Apply filters based on request parameters with ease
Modular Architecture: Customize your filter implementation using traits
Smart Caching: Intelligent caching with automatic cache key generation
User-Specific Filtering: Easily implement user-scoped filters
Rate Limiting: Control filter complexity to prevent abuse
Performance Monitoring: Track execution time and query performance
Memory Management: Optimize memory usage for large datasets
Query Optimization: Select specific columns and eager-load relationships
Filter Chaining: Chain multiple filter operations with a fluent API
Laravel 12 Support: Ready for the latest Laravel version

Getting Started

Installation is simple with Composer:

composer require jerome/filterable

Creating Your First Filter

Create a filter class using the provided Artisan command:

php artisan make:filter PostFilter

This generates a well-structured filter class:

namespace App\Filters;

use Filterable\Filter;
use Illuminate\Database\Eloquent\Builder;

class PostFilter extends Filter
{
    protected array $filters = ['status', 'category'];

    protected function status(string $value): Builder
    {
        return $this->builder->where('status', $value);
    }

    protected function category(int $value): Builder
    {
        return $this->builder->where('category_id', $value);
    }
}

Implementing in Your Model

Add the trait to your model:

namespace App\Models;

use Filterable\Traits\Filterable;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    use Filterable;
}

Using in Your Controller

Your controller code becomes clean and maintainable:

public function index(Request $request, PostFilter $filter)
{
    $posts = Post::filter($filter)->paginate();

    return response()->json($posts);
}

That's it! Your API now supports filters like /posts?status=published&category=5.

What Makes Filterable Different?

Filterable stands out from other filtering packages due to its modular, trait-based architecture. Let's explore some of its most powerful features.

Feature Management

Enable only the features you need:

$filter->enableFeatures([
    'validation',
    'caching',
    'performance',
]);

Rate Limiting and Complexity Control

Protect your application from overly complex filter requests:

$filter->setMaxFilters(10);
$filter->setMaxComplexity(100);
$filter->setFilterComplexity([
    'complex_filter' => 10,
    'simple_filter' => 1,
]);

Memory Management for Large Datasets

Handle large datasets efficiently:

// Process with lazy loading
$filter->lazy()->each(function ($post) {
    // Process each post with minimal memory
});

// Map over results without loading all records
$titles = $filter->map(function ($post) {
    return $post->title;
});

Smart Caching

Improve performance with intelligent caching:

$filter->setCacheExpiration(60);
$filter->cacheTags(['posts', 'api']);
$filter->cacheResults(true);

Input Validation

Validate filter parameters before applying them:

$filter->setValidationRules([
    'status' => 'required|in:draft,published,archived',
    'category_id' => 'sometimes|integer|exists:categories,id',
]);

Performance Monitoring

Track execution time and query performance:

$metrics = $filter->getMetrics();
$executionTime = $filter->getExecutionTime();

Real-World Example

Let's see how Filterable brings it all together in a real-world controller:

public function index(Request $request, PostFilter $filter)
{
    // Enable features
    $filter->enableFeatures(['validation', 'caching', 'performance']);

    // Set validation rules
    $filter->setValidationRules([
        'status' => 'sometimes|in:draft,published,archived',
        'category_id' => 'sometimes|integer|exists:categories,id',
    ]);

    // Apply user scope if needed
    if ($request->has('my_posts')) {
        $filter->forUser($request->user());
    }

    // Apply pre-filters
    $filter->registerPreFilters(function ($query) {
        return $query->where('is_deleted', false);
    });

    // Apply custom filter chain
    $filter->where('is_featured', true)
           ->orderBy('created_at', 'desc');

    // Apply filters to the query
    $query = Post::filter($filter);

    // Get paginated results
    $posts = $request->has('paginate')
        ? $query->paginate($request->query('per_page', 20))
        : $query->get();

    // Return performance metrics for debugging
    $metrics = null;
    if (app()->environment('local') && $filter->hasFeature('performance')) {
        $metrics = $filter->getMetrics();
    }

    return response()->json([
        'data' => $posts,
        'metrics' => $metrics,
    ]);
}

With just a few lines of code, you've implemented a sophisticated filtering system with validation, caching, user-scoping, and performance monitoring.

Extending Filterable

One of Filterable's greatest strengths is its extensibility. Need a custom filter behavior? Simply extend the base filter class:

class PostFilter extends Filter
{
    // Override or extend methods as needed
    protected function handleFilteringException(Throwable $exception): void
    {
        Log::channel('filter-errors')->error('Filter error', [
            'exception' => $exception->getMessage(),
        ]);

        // Custom handling logic
    }
}

Laravel 12 Support

Filterable is fully compatible with Laravel 12's new application structure. If you're using Laravel 12 with its minimal setup, you can register the service provider in your bootstrap/providers.php file:

return [
    // Other providers...
    Filterable\Providers\FilterableServiceProvider::class,
];

Conclusion

Filterable offers a clean, modular approach to handling query filters in Laravel applications. With its trait-based architecture, you get exactly the features you need without unnecessary overhead. Whether you're building a simple blog or a complex data platform, Filterable helps you keep your code clean and maintainable while offering powerful filtering capabilities.

Getting Started Today

Ready to try Filterable in your Laravel application? Check out the GitHub repository and give it a star if you find it useful!

composer require jerome/filterable

We welcome contributions and feedback as we continue to improve the package. Let us know what features you'd like to see next!

Building PHPVM: A PHP Version Manager Born from Necessity

Jerome Thayananthajothy — Mon, 12 May 2025 10:26:47 +0000

As a PHP developer working across multiple projects, I found myself constantly struggling with a common problem: managing different PHP versions. Each client, each project had its own requirements. One legacy application needed PHP 7.4 for compatibility reasons, while a modern API required PHP 8.2 to leverage newer language features.

Sound familiar? If you're nodding your head, you're not alone. This is why I created phpvm, a lightweight PHP version manager inspired by the elegant simplicity of Node Version Manager (NVM).

The Problem: PHP Version Chaos

Like many developers, I work with multiple PHP applications simultaneously. Before creating phpvm, my workflow looked something like this:

Check project requirements
Manually uninstall current PHP version
Install required PHP version
Configure system to use it
Repeat steps 1-4 every time I switched projects

This process was not only time-consuming but error-prone. Sometimes I'd miss a step, resulting in cryptic errors and wasted debugging time. Other times, I'd accidentally break system dependencies that relied on specific PHP versions.

"There has to be a better way," I thought. Looking around, I found several solutions, but none had the simplicity and elegance I was seeking. As a TypeScript and PHP developer who uses tools like NVM daily, I wanted something that followed similar patterns and conventions.

The Journey to Create phpvm

Building a version manager that works across different operating systems presented numerous challenges. What works on macOS might fail on Ubuntu, and what functions on Arch Linux might break on CentOS.

The first hurdle was detecting the system's package manager. Mac users typically use Homebrew, while Linux distributions vary between apt, dnf, yum, and pacman. Each has its own syntax and peculiarities.

# A snippet showing how phpvm detects the system's package manager
if [ "$(uname)" = "Darwin" ]; then
    PKG_MANAGER="brew"
    # macOS-specific logic
else
    # Detect Linux package manager
    if command -v apt-get >/dev/null 2>&1; then
        PKG_MANAGER="apt"
    elif command -v dnf >/dev/null 2>&1; then
        PKG_MANAGER="dnf"
    # More package managers...
    fi
fi

Another significant challenge came with managing symlinks and paths. On macOS, Homebrew installs PHP in a Cellar directory, while Linux distributions typically use /usr/bin. Handling these differences while providing a consistent user experience required careful consideration.

Permissions posed yet another obstacle. Installing PHP often requires superuser privileges, but running commands as root can introduce security risks. I implemented a run_with_sudo helper function that elevates privileges only when necessary.

Testing across multiple environments was perhaps the most time-consuming part. I needed to ensure phpvm worked correctly not just on my machine but on various Linux distributions and macOS versions. This led me to create a comprehensive self-testing system:

phpvm test

This command runs a series of tests that verify core functionality, giving users confidence that everything is working as expected.

The Solution: phpvm in Action

After several iterations, phpvm emerged as a robust solution. Here's how it transforms the PHP version management workflow:

# Install a specific PHP version
phpvm install 8.1

# Switch to that version
phpvm use 8.1

# Check the active version
php -v
# Output: PHP 8.1.13

# Switch to another version
phpvm use 7.4

# Verify the change
php -v
# Output: PHP 7.4.33

For teams working on the same project, phpvm supports automatic version switching via a .phpvmrc file:

# Create a .phpvmrc file in your project root
echo "8.2" > .phpvmrc

# Later, when entering the project directory
phpvm auto
# Output: Auto-switching to PHP 8.2 (from /path/to/project/.phpvmrc)

This feature ensures all team members use the correct PHP version, eliminating the "works on my machine" syndrome.

Technical Design Decisions

Several design principles guided phpvm's development:

Shell Compatibility: Written in POSIX-compliant shell script to ensure maximum compatibility across systems.
Minimal Dependencies: phpvm relies only on standard Unix tools and the system's package manager, avoiding additional dependencies.
Informative Feedback: Every operation provides clear, timestamped output, making it easier to understand what's happening:

2025-05-12 10:15:30 [INFO] Switching to PHP 8.1...
2025-05-12 10:15:32 [INFO] Switched to PHP 8.1.

Robust Error Handling: When something goes wrong, phpvm provides detailed error messages and suggestions, rather than failing silently.
Automated Testing: The built-in testing framework ensures reliability across different environments.

These decisions contribute to a tool that's not only functional but also maintainable and user-friendly.

Looking Ahead: The Future of phpvm

While phpvm successfully solves the PHP version management problem, I see several exciting possibilities for its future:

Try phpvm Today

If you're tired of the PHP version management dance, I invite you to try phpvm:

curl -o- https://raw.githubusercontent.com/Thavarshan/phpvm/main/install.sh | bash

The project is open source and available at github.com/Thavarshan/phpvm. I welcome your feedback, bug reports, and contributions! Whether you're using phpvm daily or just trying it out, your experience helps shape its future.

The journey of creating phpvm reminded me that great developer tools often arise from personal frustrations. By solving my own PHP version management headaches, I hope to help others streamline their workflows and focus on what truly matters—building great PHP applications.

What developer tools have you created to solve your own problems? I'd love to hear about your experiences in the comments below.

Bringing JavaScript’s fetch() to PHP (Sort Of)

Jerome Thayananthajothy — Mon, 12 May 2025 10:05:34 +0000

If you’ve worked across both frontend and backend stacks, you’ve probably felt the contrast.

On the frontend, JavaScript offers an elegant experience. Making an HTTP request is as simple as:

const res = await fetch('/api/data');
const data = await res.json();

It’s expressive, minimal, and easy to reason about.

But then you switch over to PHP, and the flow changes. You reach for a well-established library like Guzzle or Symfony’s HTTP client, and suddenly things feel a bit heavier. There’s nothing wrong with them — in fact, they’re excellent. But the ergonomics are just... different.

That friction sparked a small idea.

What if PHP had something that felt like JavaScript’s fetch()?

A Familiar Syntax in a Different Language

That question led to the creation of Fetch PHP, an HTTP client library designed to bring a more fluent and familiar interface to PHP.

It started as a personal experiment. The goal wasn’t to build a better HTTP client than existing ones — just one that felt more intuitive to use if you were already accustomed to JavaScript's conventions.

Here’s what that looks like in practice:

$response = fetch('https://api.example.com/data')->json();

Or, if you prefer working asynchronously with promises:

$result = await(
    fetch('https://api.example.com/data')
        ->async()
        ->withHeader('Authorization', 'Bearer ' . $token)
        ->withTimeout(5)
        ->json()
);

What It Offers

Fetch PHP isn’t a rewrite of how HTTP works in PHP — it’s an abstraction over existing standards and tools, with a focus on developer experience.

Some of the features include:

Fluent, chainable syntax for building requests
Support for synchronous and asynchronous workflows, using ReactPHP-style promises
Automatic retries with exponential backoff and error handling
PSR-7 and PSR-18 compatibility for interoperability with other libraries
PSR-3 logging support, including masking of sensitive data
Immutable request handling, reducing unintended side effects

The goal is to keep things expressive and minimal, while still offering the power and flexibility needed for real-world use.

Lessons from Building It

The process of building Fetch PHP was a reminder that language differences don’t have to limit developer experience. PHP may not be inherently asynchronous, but with the right tools, it can be. And even if it’s not JavaScript, it can still feel approachable and expressive.

It’s easy to underestimate the impact of ergonomics. Developer comfort matters — and sometimes, reaching for a more intuitive syntax can make a meaningful difference in how you approach and enjoy your work.

Give It a Try

If you’ve ever found yourself wishing PHP had a more streamlined way to work with HTTP, Fetch PHP might be worth a look.

Feedback and contributions are always welcome.

Introducing Fetch PHP 3.0: JavaScript-like HTTP Requests for Modern PHP Applications

Jerome Thayananthajothy — Sun, 04 May 2025 10:36:07 +0000

We're excited to announce the release of Fetch PHP 3.0, a major update to our HTTP client library that brings the intuitive experience of JavaScript's fetch() API to PHP developers. This release represents a significant advancement in how PHP applications can handle HTTP requests, with powerful new features for both synchronous and asynchronous operations.

The Vision Behind Fetch PHP

When we first created Fetch PHP, our goal was simple: to bring the elegance and simplicity of JavaScript's fetch API to the PHP ecosystem. Frontend developers have long enjoyed the intuitive nature of fetch() for making HTTP requests, and we wanted backend developers to have the same experience.

With version 3.0, we've taken this vision even further by enhancing the library with more powerful features while maintaining the clean, intuitive API that made it popular.

What's New in Version 3.0

True Asynchronous Support

Fetch PHP 3.0 introduces full asynchronous request capabilities powered by our custom Matrix async engine. This allows PHP developers to write non-blocking code with JavaScript-like syntax:

// Provided by Matrix PHP (https://github.com/Thavarshan/matrix)
use function async;
use function await;

// Promise-based approach
async(fn () => fetch('https://api.example.com/users'))
    ->then(fn ($response) => $response->json())
    ->catch(fn ($error) => handleError($error));

// Or using async/await pattern
$response = await(async(fn () => fetch('https://api.example.com/users')));
$users = $response->json();

This async capability is game-changing for PHP applications that need to perform multiple concurrent operations, such as fetching data from several APIs or services simultaneously.

Enhanced Fluent API

The fluent API has been significantly improved in version 3.0, offering more flexibility and cleaner syntax:

$response = fetch()
    ->baseUri('https://api.example.com')
    ->withHeaders(['Accept' => 'application/json'])
    ->withToken('your-access-token')
    ->withJson(['name' => 'John Doe', 'email' => 'john@example.com'])
    ->post('/users');

This chainable approach makes building complex requests intuitive and readable, reducing the cognitive load when working with HTTP requests.

Advanced Concurrency Controls

Version 3.0 introduces robust tools for managing concurrent requests, inspired by JavaScript's Promise API:

use function async;
use function await;
use function all;

// Run multiple requests in parallel
$results = await(all([
    'users' => async(fn () => fetch('https://api.example.com/users')),
    'posts' => async(fn () => fetch('https://api.example.com/posts')),
    'comments' => async(fn () => fetch('https://api.example.com/comments'))
]));

// Access results
$users = $results['users']->json();
$posts = $results['posts']->json();

This pattern is ideal for dashboard applications, aggregation services, or any scenario where you need to collect data from multiple sources efficiently.

Intelligent Retry Mechanism

Fetch PHP 3.0 includes a sophisticated retry system with exponential backoff:

$response = fetch()
    ->retry(3, 100)  // 3 retries with 100ms initial delay
    ->get('https://api.example.com/unstable-endpoint');

The library automatically retries failed requests with increasing delays between attempts, making your applications more resilient against transient network issues or service outages.

Comprehensive Response Object

The Response class has been enhanced with more methods for working with different content types:

$response = fetch('https://api.example.com/users/1');

// JSON handling
$user = $response->json();

// Status checking
if ($response->isOk()) {
    // Success
} elseif ($response->isNotFound()) {
    // Handle 404
}

// Header access
$contentType = $response->header('Content-Type');

The response object now implements ArrayAccess, allowing you to use array syntax to access JSON response data directly:

$userId = $response['id'];
$userName = $response['name'];

Performance Improvements

Performance has been a key focus for version 3.0. We've optimized the core request handling to reduce overhead, resulting in:

Faster response times for synchronous requests
Lower memory usage during concurrent operations
Better handling of large response bodies
More efficient connection pooling

These improvements make Fetch PHP 3.0 suitable for high-performance applications that need to process many requests quickly and efficiently.

Upgrading from Previous Versions

For users of Fetch PHP 2.x, upgrading to version 3.0 is straightforward in most cases. We've maintained backwards compatibility with the core API while adding new features. A few breaking changes were necessary to support the new async capabilities.

Getting Started

Ready to try Fetch PHP 3.0? Installation is simple with Composer:

composer require jerome/fetch-php

Our comprehensive documentation includes a quick start guide, detailed API reference, and numerous examples to help you get up and running quickly.

The Future of Fetch PHP

With version 3.0, Fetch PHP has matured into a robust, feature-rich HTTP client that bridges the gap between frontend and backend development patterns. We're committed to continuing this evolution with future enhancements focused on:

Expanded middleware support
Additional content type handlers
More advanced caching mechanisms
Enhanced debugging tools

Conclusion

Fetch PHP 3.0 represents a significant step forward in how PHP developers can interact with HTTP resources. By combining the familiar, intuitive syntax of JavaScript's fetch API with the power and flexibility of PHP, we've created a library that makes complex HTTP operations simpler and more maintainable.

Whether you're building APIs, integrating with third-party services, or developing microservices, Fetch PHP 3.0 provides the tools you need to handle HTTP requests elegantly and efficiently.

We're excited to see what you build with it!

Fetch PHP is an open-source project. We welcome contributions, feedback, and feature requests on our GitHub repository.

Type-Safe Form Handling in Laravel + Vue.js with Formlink

Jerome Thayananthajothy — Fri, 18 Oct 2024 17:21:57 +0000

Forms are the backbone of web applications, yet handling them properly can be surprisingly complex. From validation to file uploads, CSRF protection to progress tracking, there's a lot that can go wrong. That's where Formlink comes in - a TypeScript-first form handling library that bridges Laravel and Vue.js applications with elegant simplicity.

The Problem with Traditional Form Handling

Traditional form handling often involves a lot of boilerplate code. You need to:

Manually track form state
Handle validation errors
Deal with file uploads
Manage CSRF tokens
Track submission progress
Type everything correctly

Let's look at how Formlink solves these challenges with its type-safe approach.

Getting Started with Formlink

First, install Formlink using your preferred package manager:

npm install formlink

The magic of Formlink lies in its TypeScript integration. Let's start with a simple example:

interface ContactForm {
  name: string;
  email: string;
  message: string;
}

const form = useForm<ContactForm>({
  name: '',
  email: '',
  message: ''
});

By defining an interface, we get complete type safety throughout our form handling. Try to assign a number to the email field? TypeScript will catch that error before it ever reaches your users.

The Power of Type-Safe Validation

One of the most powerful features of Formlink is its type-safe validation system. Here's how it works:

interface ValidationRule {
    validate: (value: any) => boolean | Promise<boolean>;
    message: string;
}

interface ValidationRules<T extends object> {
    [K in keyof T]?: Array<ValidationRule>;
}

This type system ensures that:

You can only validate fields that actually exist in your form
Validation rules are properly structured
Error messages are always present

Real-World Example

Let's look at a complete example that showcases Formlink's capabilities:

<template>
  <form @submit.prevent="submit">
    <div>
      <input v-model="form.email" type="email" />
      <span v-if="form.errors.email" class="error">
        {{ form.errors.email }}
      </span>
    </div>

    <div>
      <input type="file" @change="handleFile" />
      <div v-if="form.progress" class="progress">
        {{ form.progress.percentage }}% uploaded
      </div>
    </div>

    <button type="submit" :disabled="form.processing">
      {{ form.processing ? 'Sending...' : 'Send' }}
    </button>
  </form>
</template>

Advanced Features That Make Life Easier

Progress Tracking

Formlink provides built-in progress tracking for file uploads. No more guessing when your files will finish uploading:

form.post('/api/upload', {
  onProgress: (progress) => {
    console.log(`${progress.percentage}% uploaded`);
  }
});

Form Transformation

Need to clean up your data before submission? Formlink's transform method has you covered:

form.transform((data) => ({
  ...data,
  email: data.email.trim().toLowerCase()
}));

Reactive Form State

Track your form's state effortlessly with reactive properties:

form.processing: Is the form being submitted?
form.progress: Track upload progress
form.errors: Access validation errors
form.isDirty: Has the form been modified?

Why Choose Formlink?

Type Safety: Full TypeScript support means fewer runtime errors and better developer experience
Zero Configuration: Works out of the box with Laravel
Built-in CSRF Protection: No need to manually handle CSRF tokens
Progress Tracking: Real-time file upload progress without extra code
Smart Error Handling: Automatic Laravel validation error handling
Framework Agnostic: While optimized for Laravel, it works with any backend

Performance Considerations

Formlink is designed to be lightweight and efficient. It only includes what you need and nothing more. The TypeScript-first approach means you catch errors at compile time rather than runtime, leading to more reliable applications.

Final Thoughts

Form handling doesn't have to be complicated. With Formlink, you get a type-safe, feature-rich solution that makes form handling in Laravel + Vue.js applications a breeze. The combination of TypeScript's type safety and Formlink's intuitive API means you can focus on building features rather than fighting with form handling.

Try it out in your next project, and experience the difference that proper type-safe form handling can make. Your future self (and your team) will thank you.

Remember, good form handling is about more than just sending data to the server - it's about providing a smooth, error-free experience for your users while maintaining developer sanity. Formlink helps you achieve both.

Meet phpvm: Your New PHP Best Friend Forever!

Jerome Thayananthajothy — Sat, 05 Oct 2024 22:41:25 +0000

Howdy, PHP aficionados and version-juggling ninjas! Are you tired of the PHP version tango? You know, that dance where you're constantly switching between PHP versions faster than a cat video goes viral? Well, put on your party hats because I've got some exciting news that'll make your development life easier (and dare I say, more fun)!

Introducing phpvm: The PHP Version Manager of Your Dreams

Picture this: You're working on a legacy project that runs on PHP 7.2, but your shiny new side project is built on PHP 8.1. Normally, this would be the part where you pull your hair out and question your life choices. But not anymore! Enter phpvm, your new PHP version management bestie.

What's the Big Deal?

phpvm is like a magic wand for PHP versions. With just a few simple commands, you can:

Install multiple PHP versions faster than you can say "Laravel"
Switch between PHP versions smoother than a barista makes a latte
Manage your PHP versions like a boss, without breaking a sweat

How to Get This Magic in Your Life

Getting started with phpvm is easier than explaining why you need another JavaScript framework. Just run this command:

curl -o- https://raw.githubusercontent.com/Thavarshan/phpvm/0.0.1/bin/install.sh | bash

Or if you're more of a wget person:

wget -qO- https://raw.githubusercontent.com/Thavarshan/phpvm/0.0.1/bin/install | bash

And voilà! You're ready to rock the PHP version management world!

Let's See This Baby in Action!

Want to install PHP 8.1? Easy peasy:

phpvm install 8.1

Need to switch to PHP 7.4 for that legacy project? No problemo:

phpvm use 7.4

Want to see all your installed PHP versions? We've got you covered:

phpvm list

It's so simple, even your cat could do it (if they had opposable thumbs, that is).

Why You'll Love phpvm

It's fast: Switch PHP versions faster than you can say "deprecated function".
It's flexible: Works on Unix-like systems, including macOS and Linux.
It's friendly: No need for sudo hugs – phpvm plays nice with your system.
It's fantastic: Manage global PHP settings and extensions like a pro.

Join the phpvm Party!

Now, I know what you're thinking: "This sounds too good to be true!" But trust me, it's real, and it's spectacular. And the best part? It's open source!

So, here's what you can do to join in on the fun:

Star the repository: Show some love on GitHub. It's like a high-five for code!
Found a bug? Open an issue! It's like playing detective, but for code.
Have an idea? Submit a pull request! It's like bringing a dish to a potluck, but the dish is code, and the potluck is our GitHub repo.
Spread the word: Tell your friends, your colleagues, your rubber duck – everyone needs to know about phpvm!

The Final Act

Say goodbye to PHP version headaches and hello to smooth sailing with phpvm. It's time to make PHP version management as enjoyable as binge-watching your favorite TV show.

So, what are you waiting for? Dive in, give phpvm a spin, and let's make PHP development great again!

Remember, with great power comes great responsibility... to have fun while coding! Happy PHP-ing, folks!

FetchPHP 2.0: An Update To Bring Javascript's Fetch & True Async To PHP (Now With Superpowers!)

Jerome Thayananthajothy — Mon, 30 Sep 2024 22:14:39 +0000

Hello lovely people!

We are thrilled to announce the release of FetchPHP 2.0! This new version is crafted to simplify HTTP requests in PHP, enhancing your development experience with greater ease and efficiency. If you have ever faced challenges with asynchronous operations in PHP, FetchPHP 2.0 is the perfect solution for you.

The Journey: From FetchPHP to a More Powerful Version

The inception of FetchPHP stemmed from a straightforward observation: PHP developers deserve the same ease of use that JavaScript developers enjoy with fetch. FetchPHP was created to bring the simplicity of JavaScript’s HTTP handling to the PHP ecosystem. But innovation didn't stop at version 1.0. With the release of FetchPHP 2.0, we've taken it a step further. This version not only simplifies the use of HTTP clients but also complements PHP's native asynchronous functionality (PHP Fibers), providing a tool that truly transforms the way you handle HTTP requests in PHP.

What’s New in FetchPHP 2.0?

FetchPHP 2.0 is packed with powerful features aimed at enhancing both simplicity and performance:

True Asynchronous Execution: FetchPHP 2.0 introduces true non-blocking asynchronous operations by utilizing PHP Fibers, thanks to the Matrix package. This advancement provides concurrency in PHP like never before, making your applications faster and more efficient.
JavaScript-Like Syntax: Developers coming from a JavaScript background will find FetchPHP’s new async/await-like syntax very familiar, allowing for seamless transitions between languages.
Fluent API: Inspired by Laravel’s HTTP client, FetchPHP’s fluent API allows you to build and chain HTTP requests effortlessly, ensuring clarity and simplicity in even the most complex operations.
Enhanced Error Handling: FetchPHP 2.0 provides customizable error management through an improved ErrorHandler. Whether you need to retry, pause, resume, or cancel requests, the control is entirely in your hands.
Synchronous Requests with Guzzle: While FetchPHP’s asynchronous capabilities are powered by Matrix, synchronous requests are managed with the reliable Guzzle HTTP client, ensuring robust performance across all request types.

Advanced Features for Modern Development

FetchPHP 2.0 is designed to handle more complex scenarios without compromising on simplicity. Consider this example:

async(fn () => fetch()
    ->baseUri('https://api.example.com')
    ->withHeaders(['X-API-Key' => 'your-key'])
    ->withBody(json_encode(['data' => 'value']))
    ->withProxy('tcp://localhost:8080')
    ->timeout(5)
    ->retry(3, 1000)
    ->post('/endpoint'))
    ->then(fn ($response) => handleResponse($response->json()))
    ->catch(fn ($e) => logError($e));

This demonstrates the power of FetchPHP 2.0 to handle asynchronous requests, proxies, retries, timeouts, and more—all while maintaining clean, readable code.

Why Choose FetchPHP Over Guzzle?

Let’s compare FetchPHP 2.0 with Guzzle to see how FetchPHP brings unique advantages to PHP developers:

Asynchronous Execution: Guzzle uses promises for async operations, while FetchPHP takes advantage of PHP Fibers, providing true non-blocking concurrency.
Familiar Syntax: FetchPHP offers a JavaScript-like syntax, making it intuitive for developers who are familiar with modern JavaScript or who prefer a streamlined, less verbose approach.
Advanced Error Handling: FetchPHP’s ErrorHandler offers flexible control over error states, allowing developers to manage requests dynamically.
Ease of Use: FetchPHP’s fluent API simplifies complex HTTP operations, providing a more natural and elegant way to structure requests.

A Practical Example: Guzzle vs. FetchPHP

// Guzzle example
$promise = $client->requestAsync('GET', 'http://httpbin.org/get');
$promise->then(function ($response) {
        echo 'Request completed: ' . $response->getBody();
    });

// FetchPHP example
async(fn () => fetch('http://httpbin.org/get'))
    ->then(fn ($response) => echo 'Request completed: ' . $response->body())
    ->catch(fn ($e) => echo 'Request failed: ' . $e->getMessage());

FetchPHP not only reduces boilerplate code but also introduces a more natural way of handling asynchronous operations in PHP.

FetchPHP 2.0: A New Era of PHP HTTP Requests

FetchPHP 2.0 is a powerful, flexible, and intuitive tool that simplifies the process of handling HTTP requests in PHP. Whether you are building small APIs or managing large-scale systems that require thousands of concurrent requests, FetchPHP has the capabilities to enhance your project.

Head over to our GitHub repository to explore FetchPHP, contribute to the project, and don't forget to give us a star on the repository to show your support. Let’s move the PHP ecosystem forward, one asynchronous request at a time.

With FetchPHP 2.0, we’re not just improving how you make HTTP requests in PHP—we’re redefining it. Take control of your HTTP operations with true asynchronous capabilities, a developer-friendly API, and powerful error handling. This is more than an update. It’s a revolution.

Explore the future of PHP HTTP requests with FetchPHP 2.0.

Exploring Matrix: Bringing JavaScript-like Async to PHP

Jerome Thayananthajothy — Sun, 29 Sep 2024 23:54:49 +0000

Are you a PHP developer who's envied the simplicity of JavaScript's async/await paradigm? Do you wish you could manage asynchronous tasks in PHP with the same ease? Look no further! Today, we're diving deep into Matrix, a cutting-edge PHP library that brings the power of JavaScript-like async operations to the PHP ecosystem.

What is Matrix?

Matrix is an innovative PHP library designed for asynchronous task management. It draws inspiration from JavaScript's async/await paradigm but leverages PHP's native Fibers to provide true non-blocking concurrency. With Matrix, you can run tasks, manage errors, and handle results—all without the need for explicit task starting.

The Power of PHP Fibers

At the heart of Matrix lies PHP Fibers, a feature introduced in PHP 8.1. But what exactly are Fibers, and how do they revolutionize asynchronous programming in PHP?

Understanding PHP Fibers

Fibers in PHP are lightweight cooperative concurrency primitives. They allow you to create sections of code that can be paused and resumed, enabling cooperative multitasking within a single PHP thread. This is a game-changer for handling I/O-bound operations, as it allows other code to run while waiting for slow operations to complete.

How Fibers Power Matrix

Matrix harnesses the power of Fibers to create a non-blocking, concurrent execution environment. When you create a task in Matrix, it's wrapped in a Fiber. This allows the task to be suspended and resumed without blocking the entire PHP process, enabling true asynchronous behavior.

The Architecture of Matrix

Matrix is built around several key components that work together to provide a seamless async experience:

AsyncHelper: This class provides the JavaScript-like async API, allowing you to chain then() and catch() methods.
Task: The core unit of work in Matrix, representing an operation that can be started, paused, resumed, or canceled.
Handler: Manages error handling and retries, providing robust fault tolerance.

These components are designed to work seamlessly together, providing a cohesive and intuitive API for managing asynchronous operations.

Benefits of Using Matrix

Simplified Async Code: Write cleaner, more readable asynchronous code that closely resembles JavaScript's async/await.
True Concurrency: Leverage PHP Fibers for non-blocking execution of multiple tasks.
Flexible Error Handling: Customize error recovery strategies with the powerful Handler class.
Fine-grained Control: Manage task lifecycles with methods for pausing, resuming, and canceling tasks.
Familiar API: If you're coming from a JavaScript background, you'll feel right at home with Matrix's API.

Usage Example

Let's look at a simple example of how you can use Matrix in your PHP projects:

use Matrix\AsyncHelper;
use function Matrix\async;

// Define an asynchronous task
$task = async(function () {
    // Simulate a time-consuming operation
    yield;
    return "Task completed successfully!";
});

// Handle the task result
$task->then(function ($result) {
    echo $result; // Output: Task completed successfully!
})->catch(function ($error) {
    echo "An error occurred: " . $error->getMessage();
});

In this example, we define an asynchronous task using the async function. The task simulates a time-consuming operation with yield. We then use the then() method to handle the successful result and catch() to handle any errors.

Future Improvements

While Matrix already offers a powerful set of features, there's always room for growth. Some potential areas for future improvement include:

Enhanced Parallel Execution: Implement methods for running multiple tasks in parallel and aggregating their results.
Integration with Popular Frameworks: Develop plugins or extensions for seamless integration with popular PHP frameworks like Laravel or Symfony.
Performance Optimizations: Continually refine the underlying Fiber management for even better performance.
Extended Monitoring and Debugging Tools: Implement more advanced tools for monitoring task execution and debugging async flows.

Conclusion

Matrix represents a significant step forward in PHP's async capabilities. By bringing a JavaScript-like async experience to PHP and leveraging the power of Fibers, it offers developers a powerful new tool for managing asynchronous operations.

Whether you're building a high-performance API, managing complex background jobs, or simply looking to write cleaner async code, Matrix deserves a place in your PHP toolbox. Give it a try in your next project and experience the future of asynchronous PHP programming today!

Ready to get started? Check out the Matrix GitHub repository and join the async revolution in PHP!

Effortless Secret Management for Laravel & JS Projects with Secrets Loader

Jerome Thayananthajothy — Thu, 19 Sep 2024 18:04:34 +0000

Managing sensitive data like API keys, tokens, and credentials across various environments can be quite tricky, especially when developing and deploying applications. Ensuring secrets are securely stored and fetched when needed, without hardcoding them into version control, is crucial for maintaining security.

That's why I created Secrets Loader, a Bash script that dynamically fetches secrets from AWS SSM and CloudFormation directly into your .env file, making local development and deployment easier, safer, and more efficient.

What is Secrets Loader?

Secrets Loader is a simple tool designed to automatically fetch secrets from AWS SSM Parameter Store and AWS CloudFormation outputs based on custom syntax in your .env file. It replaces placeholders with actual secrets without ever exposing sensitive information in version control.

For example, instead of hardcoding your API keys or credentials, you define them in your .env file like this:

THIRD_PARTY_API_KEY="ssm:/third-party/api/key"
AWS_ACCESS_KEY_ID="cf:my-stack:AccessKeyId"

With a single command, Secrets Loader will fetch the actual values from AWS and update your .env file, keeping sensitive information secure and easy to manage.

Why I Built It

During local development and deployment, I found myself dealing with sensitive credentials that I didn't want hardcoded into the project files. Having used AWS services extensively, I wanted a way to integrate secret management into my existing development workflow without too much hassle.

Here are the main challenges Secrets Loader solves:

Avoiding hardcoded secrets: No more committing secrets to version control. You can safely use placeholders and dynamically fetch the actual values from AWS SSM and CloudFormation.
Reducing manual effort: Instead of manually copying and pasting secret values, just define them once in your .env file, and let the script do the fetching.
Simplifying secret management: Whether you're working in local development, staging, or production, Secrets Loader ensures that secrets are securely and automatically loaded.

Features

Secrets Loader comes with a few key features that make it a handy tool for both local development and production environments:

Automated secret loading: Fetch secrets from AWS SSM Parameter Store and CloudFormation by specifying paths in your .env file.
Security-first approach: Keep sensitive data out of version control by securely loading it at runtime.
Simple syntax: Use a custom syntax in your .env file (ssm: for SSM parameters, cf: for CloudFormation outputs) to specify where secrets should come from.
Error handling: The script continues to process other secrets even if one retrieval fails, logging warnings without stopping your workflow.

How It Works

The magic of Secrets Loader lies in its ability to fetch secrets from AWS based on specific prefixes (ssm: and cf:). Here's an example workflow:

Set up your .env file:

Add placeholders for your secrets in your .env file using the ssm: prefix for SSM parameters or the cf: prefix for CloudFormation outputs:

   THIRD_PARTY_API_KEY="ssm:/third-party/api/key"
   AWS_SECRET_ACCESS_KEY="cf:my-stack:SecretAccessKey"

Run the script:

Use the following command to run the script and fetch the secrets:

   ./secrets.sh

Updated .env file:

After running the script, your .env file will be updated with the actual values fetched from AWS:

   THIRD_PARTY_API_KEY=actual-api-key-value
   AWS_SECRET_ACCESS_KEY=actual-access-key-value

No more hardcoding secrets, and no more manual lookups!

Installation & Setup

Ready to get started? Here's how you can set up Secrets Loader in your project:

Clone the repository:

   git clone https://github.com/Thavarshan/secretst-loader.git
   cd secretst-loader

Make the script executable:

   chmod +x secrets.sh

Ensure AWS CLI is installed and configured:

If you don’t have the AWS CLI installed, follow the AWS CLI installation guide. After installing, configure your AWS credentials:

   aws configure

Define your secrets in .env:

Use the ssm: and cf: prefixes to define where secrets should come from:

   THIRD_PARTY_API_KEY="ssm:/third-party/api/key"
   AWS_ACCESS_KEY_ID="cf:my-stack:AccessKeyId"

Example Usage

Let’s take a look at a simple example:

`.env.example` File:

# Application settings
APP_NAME=MyApp
APP_ENV=production

# Secrets fetched from AWS SSM and CloudFormation
THIRD_PARTY_API_KEY="ssm:/third-party/api/key"
AWS_SECRET_ACCESS_KEY="cf:my-stack:SecretAccessKey"

Running Secrets Loader:

./secrets.sh

Updated `.env` File:

# Application settings
APP_NAME=MyApp
APP_ENV=production

# Fetched secrets
THIRD_PARTY_API_KEY=actual-api-key-value
AWS_SECRET_ACCESS_KEY=actual-secret-access-key

Troubleshooting

If you encounter any issues while using Secrets Loader, here are a few things to check:

AWS Permissions: Ensure that the AWS CLI is configured correctly and that your IAM role or user has sufficient permissions to access AWS SSM and CloudFormation secrets.
Syntax Errors: Double-check the syntax in your .env file to make sure the ssm: and cf: prefixes are correct.
Script Errors: If the script fails to fetch certain secrets, it will log warnings but continue fetching the others. Review the logs for any error messages and make sure the AWS resources exist and are accessible.

Extending Secrets Loader

The script is designed to be extensible. If you'd like to integrate other secret management systems (like Azure Key Vault or HashiCorp Vault), you can easily modify the script to support new prefixes and fetch logic.

For example, you could add an azkv: prefix to fetch secrets from Azure Key Vault and handle the retrieval using the Azure CLI.

Contributing

Secrets Loader is open-source, and contributions are always welcome! If you'd like to add features, fix bugs, or suggest improvements, feel free to:

Open an issue: Share your feedback or bug reports.
Submit a pull request: Contribute code by following our CONTRIBUTING guidelines.

Conclusion

If you're tired of manually managing secrets across environments, Secrets Loader is a simple, effective tool to streamline the process. By fetching secrets dynamically from AWS SSM and CloudFormation, you can securely manage your credentials without risking exposure in version control.

Check out the project on GitHub, give it a try, and if you find it useful, give us a ⭐ on GitHub! Your support helps the project grow, and we'd love to hear your feedback or see your contributions to its ongoing development.