zpm-packages/server-access-laravel

Laravel integration layer for database-backed and direct-mode server access management on top of zpm-packages/server-access.

v1.0.0 2026-05-06 03:17 UTC

Requires

• php: ^8.2
• illuminate/console: ^11.0|^12.0|^13.0
• illuminate/database: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0
• zpm-packages/server-access: ^1.0

MIT

README

Laravel integration for zpm-packages/server-access. It adds Laravel service registration, Eloquent-backed synchronization, configured server resolution, direct-mode access to the current machine, scheduled sync support, and package migrations/models for server, user, and key records.

What This Package Adds

• Laravel service container bindings for the SSH manager resolver and helper services.
• Config-driven server access for current-system or remote-manager workflows.
• Database-backed sync for SshServer, SshUser, and SshKey models.
• Direct-mode records for working without syncing to database tables.
• Artisan commands to bootstrap and resync server-access tables.
• Scheduled syncing when database mode is enabled.

Installation

composer require zpm-packages/server-access-laravel

If you want package configuration in your app:

php artisan vendor:publish --tag=ssh-management-config

If you want the package database tables:

php artisan migrate

Or let the package run the initial migration and sync flow for you:

php artisan ssh-management:setup-db

Default Config

The package exposes config/ssh-management.php.

return [
	'sync_with_database' => false,
	'allow_manager_password_update' => false,
	'database_sync_schedule' => 'hourly',
	'models' => [
		'server' => ZPMPackages\LaravelSshManagement\Models\SshServer::class,
		'user' => ZPMPackages\LaravelSshManagement\Models\SshUser::class,
		'key' => ZPMPackages\LaravelSshManagement\Models\SshKey::class,
	],
	'servers' => [
		'current-system' => [
			'name' => 'Current System',
			'host' => null,
			'port' => 22,
			'operating_system' => 'linux',
			'manager_username' => env('SSH_MANAGER_USERNAME'),
			'manager_password' => env('SSH_MANAGER_PASSWORD'),
			'is_current_system' => true,
		],
	],
];

Mode 1: Direct Mode

Set sync_with_database to false when you want to read and mutate the current system or configured servers without persisting SSH users and keys to the package database tables.

Example Config

'sync_with_database' => false,

'servers' => [
	'current-system' => [
		'name' => 'Current System',
		'host' => null,
		'port' => 22,
		'operating_system' => PHP_OS_FAMILY === 'Windows' ? 'windows' : 'linux',
		'manager_username' => env('SSH_MANAGER_USERNAME'),
		'manager_password' => env('SSH_MANAGER_PASSWORD'),
		'is_current_system' => true,
	],
],

List Configured Servers

use ZPMPackages\LaravelSshManagement\Services\SshDirectDataService;

$servers = app(SshDirectDataService::class)->listServers();

Find a Configured Server

$server = app(SshDirectDataService::class)->findServer('current-system');

List Direct Users

$users = app(SshDirectDataService::class)->listUsers('current-system');

Create a Direct User

$user = app(SshDirectDataService::class)->createUser([
	'username' => 'deploy',
	'name' => 'Deploy User',
	'home_directory' => '/home/deploy',
	'groups' => ['deploy', 'www-data'],
	'comment' => 'Deployment account',
	'is_root' => false,
	'can_read_entries' => true,
	'can_write_entries' => true,
	'can_manage_entries' => false,
	'managed_directories' => ['/srv/apps'],
], 'current-system');

Update or Delete a Direct User

$updated = app(SshDirectDataService::class)->updateUser($user, [
	'comment' => 'Updated deployment account',
	'managed_directories' => ['/srv/apps', '/srv/releases'],
]);

app(SshDirectDataService::class)->deleteUser($updated);

Create or Generate Direct Keys

$manualKey = app(SshDirectDataService::class)->createKey($user, [
	'name' => 'CI key',
	'public_key' => 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... ci@runner',
	'public_key_path' => '.ssh/ci.pub',
	'private_key_path' => '.ssh/ci',
	'is_managed' => false,
]);

$generatedKey = app(SshDirectDataService::class)->generateKey($user, [
	'name' => 'deploy@host',
	'key_type' => 'ed25519',
	'passphrase' => 'secret-passphrase',
	'private_key_path' => '.ssh/deploy',
	'public_key_path' => '.ssh/deploy.pub',
]);

Update or Delete Direct Keys

$updatedKey = app(SshDirectDataService::class)->updateKey($user, (string) $generatedKey->getKey(), [
	'comment' => 'Rotated deploy key',
]);

app(SshDirectDataService::class)->deleteKey($user, (string) $updatedKey->getKey());

Mode 2: Database Sync Mode

Set sync_with_database to true when you want the package models to be the app-level source of truth and have the package synchronize them to the OS/provider layer.

Example Config

'sync_with_database' => true,
'database_sync_schedule' => 'hourly',

Sync One User Model to the Provider

use App\Models\SshUser;
use ZPMPackages\LaravelSshManagement\Services\SshUserManagerService;

$user = SshUser::query()->with('sshServer', 'sshKeys')->findOrFail($id);

app(SshUserManagerService::class)->syncUser($user, creating: false);

Create a User and Push It to the System

$user = SshUser::query()->create([
	'ssh_server_id' => $server->getKey(),
	'username' => 'deploy',
	'name' => 'Deploy User',
	'home_directory' => '/home/deploy',
	'groups' => ['deploy'],
	'comment' => 'Deployment user',
	'is_root' => false,
	'can_read_entries' => true,
	'can_write_entries' => true,
	'can_manage_entries' => false,
	'managed_directories' => ['/srv/apps'],
	'permissions' => [],
]);

app(SshUserManagerService::class)->syncUser(
	$user,
	server: $server,
	creating: true,
	keyPassphrase: 'secret-passphrase',
);

Delete a Synced User

app(SshUserManagerService::class)->deleteUser($user, $server);

Generate a Managed Key for an Existing User

$key = app(SshUserManagerService::class)->generateKey(
	user: $user,
	server: $server,
	label: 'deploy@host',
	keyType: 'ed25519',
	bits: null,
	comment: 'Deploy key',
	publicKeyPath: '.ssh/deploy.pub',
	privateKeyPath: '.ssh/deploy',
	passphrase: 'secret-passphrase',
);

Resolver Examples

The resolver is the main way to discover configured servers and create the underlying provider manager.

use ZPMPackages\LaravelSshManagement\Services\SshManagerResolver;

$resolver = app(SshManagerResolver::class);

$usesDatabase = $resolver->usesDatabase();
$serverModelClass = $resolver->serverModelClass();
$currentConfiguredServer = $resolver->currentConfiguredServer();
$candidates = $resolver->listCurrentSystemUsernames();
$defaultManager = $resolver->defaultCurrentSystemUsername();

$manager = $resolver->forServer($currentConfiguredServer);
$systemUsers = $manager->scanSystemUsers();

System User Management Examples

use ZPMPackages\LaravelSshManagement\Services\SshSystemUserService;

$systemUserService = app(SshSystemUserService::class);

$candidates = $systemUserService->currentSystemManagerCandidates();
$defaultManager = $systemUserService->defaultCurrentSystemManagerUsername();

$systemUserService->changeCurrentSystemManagerUser($server, 'administrator', 'current-password');
$systemUserService->updateUserPassword($user, 'new-password');

Sync Commands

Run a full database sync:

php artisan ssh-management:sync

Run migrations plus the initial sync:

php artisan ssh-management:setup-db

Scheduling

When sync_with_database is enabled, the package automatically registers the scheduled sync command after Laravel resolves the scheduler. The frequency comes from ssh-management.database_sync_schedule and defaults to hourly.

Model Customization

You can point the package at your own Eloquent models by replacing the values in ssh-management.models as long as they expose the fields and relations expected by the services.

'models' => [
	'server' => App\Models\SshServer::class,
	'user' => App\Models\SshUser::class,
	'key' => App\Models\SshEntry::class,
],

Notes

• can_read_entries, can_write_entries, and can_manage_entries are explicit booleans on the user model.
• permissions is the structured per-user permission payload that maps to SshPermissionEntity.
• changeCurrentSystemManagerUser() only supports the current-system server flow.
• Updating the active manager user's password is blocked unless ssh-management.allow_manager_password_update is enabled.