PHPackages                             jeffersongoncalves/laravel-zero-credentials - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. jeffersongoncalves/laravel-zero-credentials

ActiveLibrary[CLI & Console](/categories/cli)

jeffersongoncalves/laravel-zero-credentials
===========================================

Reusable base for storing CLI authentication credentials locally in JSON (~/.<app>/config.json or XDG), with 0600 permissions and a typed credentials contract.

v1.0.0(today)10MITPHPPHP ^8.2CI passing

Since Jun 23Pushed today1 watchersCompare

[ Source](https://github.com/jeffersongoncalves/laravel-zero-credentials)[ Packagist](https://packagist.org/packages/jeffersongoncalves/laravel-zero-credentials)[ Docs](https://github.com/jeffersongoncalves/laravel-zero-credentials)[ RSS](/packages/jeffersongoncalves-laravel-zero-credentials/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (3)Versions (2)Used By (0)

[![laravel-zero-credentials](https://raw.githubusercontent.com/jeffersongoncalves/laravel-zero-credentials/main/art/jeffersongoncalves-laravel-zero-credentials.png)](https://raw.githubusercontent.com/jeffersongoncalves/laravel-zero-credentials/main/art/jeffersongoncalves-laravel-zero-credentials.png)

laravel-zero-credentials
========================

[](#laravel-zero-credentials)

Reusable base for storing CLI authentication credentials locally in JSON, with secure file permissions and a typed credentials contract.

Extracted from the `bb-cli` and `jira-cli` Laravel Zero tools, whose `AuthService` classes were ~90% identical. This package provides the shared persistence pipeline so each CLI only declares its own credential fields.

Why
---

[](#why)

Every CLI that authenticates against an API needs to:

- resolve the user's home directory across platforms,
- write credentials to `~/./config.json` (or a custom/XDG path),
- create the directory `0700` and the file `0600`,
- cache the loaded credentials in memory,
- validate stored data before trusting it.

This package does all of that. The CLI supplies only a typed DTO and two small methods.

Installation
------------

[](#installation)

```
composer require jeffersongoncalves/laravel-zero-credentials
```

Requires PHP `^8.2`. No other dependencies.

Usage
-----

[](#usage)

### 1. Implement the credentials contract

[](#1-implement-the-credentials-contract)

```
use JeffersonGoncalves\LaravelZero\Credentials\CredentialsContract;

final class Credentials implements CredentialsContract
{
    public function __construct(
        public readonly string $username,
        public readonly string $apiToken,
    ) {}

    public static function fromArray(array $data): static
    {
        return new static(
            username: $data['username'] ?? '',
            apiToken: $data['api_token'] ?? '',
        );
    }

    public function toArray(): array
    {
        return ['username' => $this->username, 'api_token' => $this->apiToken];
    }

    public function isValid(): bool
    {
        return $this->username !== '' && $this->apiToken !== '';
    }
}
```

### 2. Extend the abstract auth service

[](#2-extend-the-abstract-auth-service)

```
use JeffersonGoncalves\LaravelZero\Credentials\AbstractAuthService;
use JeffersonGoncalves\LaravelZero\Credentials\CredentialsContract;

final class AuthService extends AbstractAuthService
{
    protected function appName(): string
    {
        return 'bb-cli'; // => ~/.bb-cli/config.json
    }

    protected function fromArray(array $data): CredentialsContract
    {
        return Credentials::fromArray($data);
    }
}
```

### 3. Use it

[](#3-use-it)

```
$auth = new AuthService;

$auth->save(new Credentials('alice', 'secret-token'));

$auth->isAuthenticated();          // true
$auth->load()->username;           // 'alice'
$auth->getConfigPath();            // /home/alice/.bb-cli/config.json

$auth->forget();                   // deletes the file
```

### Guarding commands

[](#guarding-commands)

```
use JeffersonGoncalves\LaravelZero\Credentials\AuthenticationException;

if (! $auth->isAuthenticated()) {
    throw new AuthenticationException("Run 'bb auth:save' first.");
}
```

### Custom / XDG config directory

[](#custom--xdg-config-directory)

Override `configDir()` to change where credentials live (the default is `~/.`):

```
protected function configDir(): string
{
    $base = getenv('XDG_CONFIG_HOME') ?: $this->getHomeDir().'/.config';

    return $base.'/bb-cli';
}
```

Public API
----------

[](#public-api)

ClassDescription`CredentialsContract`Interface for a typed credentials DTO: `fromArray()`, `toArray()`, `isValid()`.`AbstractAuthService`Template method base: `save()`, `load()`, `isAuthenticated()`, `forget()`, `getConfigPath()`, `getConfigDir()`, `getHomeDir()`. Subclass defines `appName()` and `fromArray()`; override `configDir()` to customize the path.`AuthenticationException``RuntimeException` with a parametrizable message (default `"Not authenticated."`).License
-------

[](#license)

MIT

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance100

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 75% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

0d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/411493?v=4)[Jefferson Gonçalves](/maintainers/jeffersongoncalves)[@jeffersongoncalves](https://github.com/jeffersongoncalves)

---

Top Contributors

[![jeffersongoncalves](https://avatars.githubusercontent.com/u/411493?v=4)](https://github.com/jeffersongoncalves "jeffersongoncalves (3 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")

---

Tags

authenticationclicomposerconfigcredentialsjeffersongoncalveslaravel-zerophpjsoncliconfigauthlaravel-zerocredentials

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/jeffersongoncalves-laravel-zero-credentials/health.svg)

```
[![Health](https://phpackages.com/badges/jeffersongoncalves-laravel-zero-credentials/health.svg)](https://phpackages.com/packages/jeffersongoncalves-laravel-zero-credentials)
```

###  Alternatives

[nunomaduro/collision

Cli error handling for console/command-line PHP applications.

4.6k348.7M10.4k](/packages/nunomaduro-collision)[nunomaduro/laravel-console-task

Laravel Console Task is a output method for your Laravel/Laravel Zero commands.

2592.3M13](/packages/nunomaduro-laravel-console-task)[nunomaduro/laravel-console-summary

A Beautiful Laravel Console Summary for your Laravel/Laravel Zero commands.

672.2M4](/packages/nunomaduro-laravel-console-summary)[nunomaduro/laravel-console-dusk

Laravel Console Dusk allows the usage of Laravel Dusk in Laravel/Laravel Zero artisan commands.

16357.3k8](/packages/nunomaduro-laravel-console-dusk)[mehrancodes/laravel-harbor

A CLI tool to Quickly create On-Demand preview environment for your apps.

10095.6k](/packages/mehrancodes-laravel-harbor)[nunomaduro/collision-adapter-symfony

Collision's adapter for Symfony applications. Error Reporting for console/command-line PHP applications.

4537.7k7](/packages/nunomaduro-collision-adapter-symfony)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)