README

⚠️ This SDK is in beta. It has not been extensively tested in production environments. Unit and integration tests are included in the source code and can be run with your own API key and SimpleMDM environment. Use in production at your own risk.

A PHP SDK for the SimpleMDM API to programmatically manage Apple devices. Compatible with Laravel and any PHP 8.1+ project. 🍎

🎉 Features

• 📱 Full device management — CRUD, lock, wipe, restart, bluetooth, lost mode, etc.
• 📦 20 API resources covering the entire SimpleMDM v1 API
• 🔄 Automatic rate limiting — smart retry on 429 errors
• 🧩 Laravel ready — Service provider, facade and dependency injection
• ⚡ Async-friendly — Guzzle HTTP under the hood
• 🧪 200 tests (unit + integration) with VCR cassettes

📍 Installation

composer require dimer47/simplemdm-php-sdk

🚀 Quick Start

use SimpleMDM\SimpleMDM;

$mdm = new SimpleMDM('your-api-key');

// List all devices
$devices = $mdm->devices->list();

// Get a specific device
$device = $mdm->devices->get(123);

// Lock a device
$mdm->devices->lock(123, [
    'message' => 'This device has been locked.',
    'phone_number' => '555-0123',
]);

🔧 Laravel Integration

⚙️ Configuration

The package auto-discovers the service provider and facade. Publish the config file:

php artisan vendor:publish --tag=simplemdm-config

Add your API key to .env:

SIMPLEMDM_API_KEY=your-api-key

🏷️ Usage with Facade

use SimpleMDM\Laravel\Facades\SimpleMDM;

$devices = SimpleMDM::devices->list();
$account = SimpleMDM::account->get();

💉 Usage with Dependency Injection

use SimpleMDM\SimpleMDM;

class DeviceController extends Controller
{
    public function index(SimpleMDM $mdm)
    {
        return $mdm->devices->list();
    }
}

📚 Available Resources

🏢 Account

$mdm->account->get();
$mdm->account->update(['name' => 'My Company']);

📱 Devices

$mdm->devices->list();
$mdm->devices->get($id);
$mdm->devices->create('Device Name', $groupId);
$mdm->devices->update($id, ['name' => 'New Name']);
$mdm->devices->delete($id);

// Actions
$mdm->devices->lock($id, ['message' => '...', 'phone_number' => '...']);
$mdm->devices->wipe($id);
$mdm->devices->restart($id);
$mdm->devices->shutdown($id);
$mdm->devices->refresh($id);
$mdm->devices->pushApps($id);
$mdm->devices->clearPasscode($id);
$mdm->devices->clearFirmwarePassword($id);
$mdm->devices->clearRestrictionsPassword($id);
$mdm->devices->updateOS($id);

// Firmware & Recovery passwords
$mdm->devices->rotateFirmwarePassword($id);
$mdm->devices->clearRecoveryLockPassword($id);
$mdm->devices->rotateRecoveryLockPassword($id);
$mdm->devices->rotateFileVaultKey($id);

// Admin password
$mdm->devices->setAdminPassword($id, ['password' => '...']);
$mdm->devices->rotateAdminPassword($id);

// Bluetooth & Remote Desktop
$mdm->devices->enableBluetooth($id);
$mdm->devices->disableBluetooth($id);
$mdm->devices->enableRemoteDesktop($id);
$mdm->devices->disableRemoteDesktop($id);

// Related data
$mdm->devices->listInstalledApps($id);
$mdm->devices->listProfiles($id);
$mdm->devices->listUsers($id);
$mdm->devices->deleteUser($deviceId, $userId);

// Custom attributes
$mdm->devices->listCustomAttributes($id);
$mdm->devices->setCustomAttribute($id, 'attribute_name', 'value');
$mdm->devices->setCustomAttributes($id, ['attr1' => 'val1', 'attr2' => 'val2']); // bulk

// Other
$mdm->devices->setTimeZone($id, 'Europe/Paris');
$mdm->devices->unenroll($id);

📦 Apps

$mdm->apps->list();
$mdm->apps->get($id);
$mdm->apps->create('/path/to/app.ipa', 'App Name');           // Upload binary
$mdm->apps->createFromAppStore('899247664', 'App Name');       // From App Store ID
$mdm->apps->createFromBundleId('com.example.app', 'App Name'); // From Bundle ID
$mdm->apps->update($id, ['name' => 'Updated Name']);
$mdm->apps->delete($id);

// Munki
$mdm->apps->uploadMunkiPkgInfo($id, '/path/to/pkginfo.plist');
$mdm->apps->deleteMunkiPkgInfo($id);

📋 Assignment Groups

$mdm->assignmentGroups->list();
$mdm->assignmentGroups->get($id);
$mdm->assignmentGroups->create('Group Name');
$mdm->assignmentGroups->update($id, ['name' => 'New Name']);
$mdm->assignmentGroups->delete($id);

// Apps
$mdm->assignmentGroups->assignApp($groupId, $appId);
$mdm->assignmentGroups->unassignApp($groupId, $appId);
$mdm->assignmentGroups->pushApps($id);
$mdm->assignmentGroups->updateApps($id);

// Devices
$mdm->assignmentGroups->assignDevice($groupId, $deviceId);
$mdm->assignmentGroups->unassignDevice($groupId, $deviceId);

// Device Groups
$mdm->assignmentGroups->assignDeviceGroup($groupId, $deviceGroupId);
$mdm->assignmentGroups->unassignDeviceGroup($groupId, $deviceGroupId);

// Profiles
$mdm->assignmentGroups->assignProfile($groupId, $profileId);
$mdm->assignmentGroups->unassignProfile($groupId, $profileId);
$mdm->assignmentGroups->syncProfiles($id);

// Other
$mdm->assignmentGroups->clone($id);
$mdm->assignmentGroups->getCustomAttributes($id);
$mdm->assignmentGroups->setCustomAttribute($id, 'attr_name', 'value');

🏷️ Custom Attributes

$mdm->customAttributes->list();
$mdm->customAttributes->get($id);
$mdm->customAttributes->create('Attribute Name', 'default_value');
$mdm->customAttributes->update($id, ['name' => 'New Name']);
$mdm->customAttributes->delete($id);

📄 Custom Configuration Profiles

$mdm->customConfigurationProfiles->list();
$mdm->customConfigurationProfiles->get($id);
$mdm->customConfigurationProfiles->create('/path/to/profile.mobileconfig');
$mdm->customConfigurationProfiles->update($id, ['name' => 'New Name']);
$mdm->customConfigurationProfiles->delete($id);
$mdm->customConfigurationProfiles->download($id);

// Per-device assignment
$mdm->customConfigurationProfiles->pushToDevice($profileId, $deviceId);
$mdm->customConfigurationProfiles->removeFromDevice($profileId, $deviceId);

// Device group assignment
$mdm->customConfigurationProfiles->assignToDeviceGroup($profileId, $deviceGroupId);
$mdm->customConfigurationProfiles->unassignFromDeviceGroup($profileId, $deviceGroupId);

📜 Custom Declarations (DDM)

$mdm->customDeclarations->list();
$mdm->customDeclarations->get($id);
$mdm->customDeclarations->create('com.apple.configuration.management.test', '/path/to/payload.json', 'Declaration Name');
$mdm->customDeclarations->update($id, ['name' => 'New Name']);
$mdm->customDeclarations->delete($id);
$mdm->customDeclarations->download($id);

// Per-device
$mdm->customDeclarations->pushToDevice($declarationId, $deviceId);
$mdm->customDeclarations->removeFromDevice($declarationId, $deviceId);

🔗 DEP Servers

$mdm->depServers->list();
$mdm->depServers->get($id);
$mdm->depServers->listDevices($id);
$mdm->depServers->getDevice($serverId, $depDeviceId);
$mdm->depServers->sync($id);

📧 Enrollments

$mdm->enrollments->list();
$mdm->enrollments->get($id);
$mdm->enrollments->delete($id);
$mdm->enrollments->sendInvitation($id, 'user@example.com');

📲 Installed Apps

$mdm->installedApps->get($id);
$mdm->installedApps->update($id);
$mdm->installedApps->delete($id);

📝 Logs

$mdm->logs->list(['namespace' => 'device']);
$mdm->logs->get($id);

📍 Lost Mode

$mdm->lostMode->enable($deviceId, [
    'message' => 'Please return this device.',
    'phone_number' => '555-0123',
]);
$mdm->lostMode->disable($deviceId);
$mdm->lostMode->playSound($deviceId);
$mdm->lostMode->updateLocation($deviceId);

⚙️ Managed App Configs

$mdm->managedAppConfigs->list($appId);
$mdm->managedAppConfigs->create($appId, 'config_key', 'config_value', 'string');
$mdm->managedAppConfigs->push($appId);
$mdm->managedAppConfigs->delete($appId, $configId);
$mdm->managedAppConfigs->deleteAll($appId);

🛡️ Profiles

$mdm->profiles->list();
$mdm->profiles->get($id);
$mdm->profiles->assignToDevice($profileId, $deviceId);
$mdm->profiles->unassignFromDevice($profileId, $deviceId);
$mdm->profiles->assignToDeviceGroup($profileId, $deviceGroupId);
$mdm->profiles->unassignFromDeviceGroup($profileId, $deviceGroupId);

🔐 Push Certificate

$mdm->pushCertificate->get();
$mdm->pushCertificate->update('/path/to/cert.pem', 'apple-id@example.com');
$mdm->pushCertificate->getSignedCsr();

📜 Scripts

$mdm->scripts->list();
$mdm->scripts->get($id);
$mdm->scripts->create('Script Name', '/path/to/script.sh', variableSupport: true);
$mdm->scripts->update($id, ['name' => 'New Name']);
$mdm->scripts->delete($id);

▶️ Script Jobs

$mdm->scriptJobs->list();
$mdm->scriptJobs->get($id);
$mdm->scriptJobs->create($scriptId, [
    'device_ids' => [1, 2, 3],
    'assignment_group_ids' => [10],
]);
$mdm->scriptJobs->cancel($id);

❌ Error Handling

use SimpleMDM\Exceptions\ApiException;
use SimpleMDM\Exceptions\AuthenticationException;
use SimpleMDM\Exceptions\RateLimitException;

try {
    $devices = $mdm->devices->list();
} catch (AuthenticationException $e) {
    // Invalid API key (401)
} catch (RateLimitException $e) {
    // Too many requests (429)
    $retryAfter = $e->getRetryAfter(); // seconds until rate limit resets
} catch (ApiException $e) {
    // Other API error
    $statusCode = $e->getStatusCode();
    $responseBody = $e->getResponseBody();
}

🧪 Testing

# Unit tests only
vendor/bin/pest tests/Unit/

# Full suite (unit + integration)
vendor/bin/pest

# With Docker
docker compose run --rm php vendor/bin/pest

Integration tests use a VCR cassette system that records real API responses and replays them. To record new cassettes, set SIMPLEMDM_API_KEY in .env and delete the corresponding cassette in tests/Fixtures/cassettes/.

📊 API Coverage

🧪 200 tests | ✅ 404 assertions | ⏭️ 17 skipped

Tests were run against the real SimpleMDM API with a supervised iPad (iOS 12.5).

🔑 Legend

⚠️ Limitations and Warnings

🔴 This SDK is in beta. Integration tests were run against a limited SimpleMDM environment (a single supervised iPad running iOS 12.5, no macOS device). While 100% of endpoints are covered by unit tests and the majority are validated through integration tests, some production scenarios could not be verified.

Endpoints not integration tested:

• 🖥️ macOS only — Remote desktop, firmware/recovery/admin passwords, FileVault, script jobs. Require an enrolled macOS device.
• 📜 DDM (Declarative Device Management) — Assigning custom declarations to a device requires iOS 15+. The test iPad runs iOS 12.
• ⛔ Wipe / Unenroll — Not tested as a precaution (destructive and irreversible).
• ⛔ Push Certificate update — Not tested (risk of breaking MDM communications).
• 🛡️ Profiles / Device Groups — Skipped if no profile or group is configured in the account.

💡 Running tests with your own environment:

# 1. Copy the environment file
cp .env.example .env

# 2. Set your SimpleMDM API key
# SIMPLEMDM_API_KEY=your-api-key

# 3. Delete cassettes to re-record with your environment
rm -rf tests/Fixtures/cassettes/*.json

# 4. Run tests
vendor/bin/pest

💡 Tip: VCR cassettes record real API responses. Once recorded, tests can be re-run without an API connection. Delete a cassette to force re-recording for that endpoint.

📖 OpenAPI Specification

An OpenAPI 3.0 specification file is available at openapi.yaml. It covers all SimpleMDM API v1 endpoints documented in this SDK (~130 endpoints). This file can be used with AI CLI tools, Swagger UI, or any OpenAPI-compatible tool to explore and interact with the API.

Note: This specification has been generated from the SDK source code and has not been extensively tested against the live API. Use it as a reference, not as a guaranteed contract.

📋 Requirements

• PHP 8.1+
• Guzzle HTTP 7.0+

📄 License

MIT