README

A modular SDK and Laravel integration for the Packagist.org API with typed DTOs, configurable caching strategies, and static analysis level max.

Requires PHP 8.4+ and Laravel 12+

Features

Type-Safe DTOs — Strict typing with readonly properties and immutability
Configurable Cache Strategies — Multiple caching strategies (remember, revalidate, forever, none)
Action Pattern — Clean separation of concerns with dedicated action classes
Full Static Analysis — PHPStan level max with Larastan
Pest Testing — Comprehensive test coverage with PestPHP
Laravel 12 Ready — Built for modern Laravel applications

Installation

Install via Composer:

composer require akira/laravel-packagist

Publish the configuration file:

php artisan vendor:publish --provider="Akira\Packagist\Providers\PackagistServiceProvider"

Configuration

Edit config/packagist.php to customize your setup:

return [
    'use' => [
        'driver' => env('PACKAGIST_CACHE_DRIVER'),
        'strategy' => \Akira\Packagist\Cache\RevalidateCache::class,
        'ttl' => (int) env('PACKAGIST_CACHE_TTL', 3600),
        'tags' => ['packagist'],
        'enabled' => (bool) env('PACKAGIST_CACHE_ENABLED', true),
    ],

    'per_action' => [
        'GetPackageAction' => [
            'strategy' => \Akira\Packagist\Cache\ForeverCache::class,
        ],
        'SearchPackagesAction' => [
            'strategy' => \Akira\Packagist\Cache\RememberCache::class,
            'ttl' => 300,
        ],
    ],
];

Usage

Get Package Information

use Akira\Packagist\Facades\Packagist;

$package = Packagist::package('laravel/framework');

echo $package->name;                    // 'laravel/framework'
echo $package->description;             // 'The Laravel Framework'
echo $package->downloads['total'];      // total downloads
echo $package->downloads['monthly'];    // monthly downloads
echo $package->downloads['daily'];      // daily downloads
echo $package->favers;                  // total favorites

Search Packages

$results = Packagist::search('laravel', [
    'type' => 'library',
    'tags' => ['framework'],
    'sort' => 'downloads',
]);

foreach ($results['results'] as $package) {
    echo $package['name'];
}

Get Statistics

$stats = Packagist::stats(['period' => 'monthly']);

Get Package Maintainers

$maintainers = Packagist::maintainers('laravel/framework');

foreach ($maintainers as $maintainer) {
    echo $maintainer['name'];
    echo $maintainer['email'];
}

Cache Strategies

RevalidateCache (Default)

Uses Laravel's cache remember() method with optional TTL revalidation.

'strategy' => \Akira\Packagist\Cache\RevalidateCache::class,

RememberCache

Standard cache remember with configurable TTL (default: 3600 seconds).

'strategy' => \Akira\Packagist\Cache\RememberCache::class,
'ttl' => 300, // 5 minutes

ForeverCache

Caches indefinitely until manually cleared.

'strategy' => \Akira\Packagist\Cache\ForeverCache::class,

NoneCache

Disables caching entirely.

'strategy' => \Akira\Packagist\Cache\NoneCache::class,

Custom Cache Implementation

Implement the CacheContract to create your own caching strategy:

use Akira\Packagist\Contracts\CacheContract;

class CustomCache implements CacheContract
{
    public function get(string $key, callable $callback, int $ttl = 0, ?string $action = null): mixed
    {
        return $callback();
    }

    public function forget(string $key): void
    {
        // Custom logic
    }
}

'strategy' => CustomCache::class,

Custom HTTP Client

Implement the ClientContract for custom HTTP handling:

use Akira\Packagist\Contracts\ClientContract;

class CustomClient implements ClientContract
{
    public function get(string $endpoint): mixed
    {
        // Custom implementation
    }

    public function search(string $query, array $filters = []): mixed
    {
        // Custom implementation
    }
}

Use it:

$manager = new PackagistManager(config('packagist'));
$manager->withClient(new CustomClient());

Testing

Run the test suite:

composer test

Run tests with coverage:

composer test:coverage

Type coverage check:

composer test:type-coverage

Code Quality

Format code with Pint:

composer lint

Refactor with Rector:

composer refactor

Static analysis with PHPStan:

composer test:types

Check refactoring rules:

composer test:refactor

API Reference

Packagist Facade

package(string $name): PackageDTO — Get package information
search(string $query, array $filters = []): array — Search packages
stats(array $filters = []): array — Get statistics
maintainers(string $package): array — Get package maintainers
withClient(ClientContract $client): PackagistManager — Use custom HTTP client
withCache(CacheContract $cache): PackagistManager — Use custom cache strategy

DTOs

PackageDTO

name: string
description: string
repository: ?string
versions: array<string, VersionDTO>
maintainers: array<MaintainerDTO>
homepage: ?string
license: ?string
downloads: array — Download statistics with total, monthly, daily
favers: int

VersionDTO

version: string
name: string
description: string
require: string
keywords: array
homepage: ?string
license: ?string
authors: array

MaintainerDTO

name: string
email: string
homepage: ?string

License

The MIT License (MIT). See LICENSE file for details.

Support

For issues, questions, or contributions, visit the GitHub repository.

akira / laravel-packagist

Maintainers

Details