The MOCO PHP SDK provides convenient access to the MOCO API from applications written in PHP. It includes a comprehensive set of pre-built services and models to simplify integration with MOCO's time tracking, project management, and invoicing platform.
- 🏗️ Service-Oriented Architecture: Clean, organized service classes for each API endpoint
- 📋 Comprehensive Entity System: Strongly typed models for all MOCO resources
- 🔧 PSR Standards Compliant: Built on PSR-7 (HTTP Message), PSR-17 (HTTP Factories), and PSR-18 (HTTP Client)
- ⚡ Automatic Parameter Validation: Built-in validation for required fields
- 🔌 Flexible HTTP Client: Works with any PSR-18 compatible HTTP client
- 🎯 Full MOCO API Coverage: Support for all major MOCO features including users, projects, activities, invoices, and more
Found a bug? We'd love to hear about it! Please help us improve the MOCO PHP SDK by reporting any issues you encounter.
🔗 Report a Bug: Create an issue on GitHub
When reporting a bug, please include:
- 📝 Clear description of the issue
- 🔄 Steps to reproduce the problem
- 🎯 Expected vs actual behavior
- 🛠️ PHP version and SDK version
- 📋 Any relevant code snippets or error messages
Your feedback helps make this library better for everyone! 🚀
- Requirements
- Installation
- Quick Start
- Authentication
- Usage Examples
- API Reference
- Contributing
- Versioning
- License
- PHP 8.2 or higher
- Required Extensions:
curl,json,mbstring - Composer for dependency management
- A valid MOCO account and API token
This library uses the following PSR-compatible packages:
psr/http-message- HTTP message interfaces (PSR-7)psr/http-client-implementation- HTTP client implementation (PSR-18)php-http/httplug- HTTP client abstractionphp-http/discovery- Automatic HTTP client discoverysymfony/http-client- Default HTTP client implementation
Install the latest version with Composer:
composer require mbs-hub/moco-phpGet up and running with the MOCO API in minutes:
<?php
require_once 'vendor/autoload.php';
use Moco\MocoClient;
// Initialize the client
$moco = new MocoClient([
'endpoint' => 'https://your-company.mocoapp.com/api/v1/',
'token' => 'your-api-token-here'
]);
// Create a new user
$user = $moco->users->create([
'firstname' => 'John',
'lastname' => 'Doe',
'email' => 'john.doe@company.com',
'password' => 'secure-password',
'unit_id' => 123456
]);
echo "User created with ID: " . $user->id;
// Get all projects
$projects = $moco->projects->get();
foreach ($projects as $project) {
echo "Project: " . $project->name . " (ID: " . $project->id . ")\n";
}
// Log time activity
$activity = $moco->activities->create([
'date' => '2024-01-15',
'hours' => 8.5,
'description' => 'Working on API integration',
'project_id' => 789,
'task_id' => 456,
'user_id' => $user->id
]);
echo "Activity logged: " . $activity->id;The MOCO PHP SDK uses token-based authentication. You'll need:
- API Token: Generate one in your MOCO account settings
- Endpoint URL: Your company-specific MOCO API endpoint
- Log into your MOCO account
- Go to Settings → API
- Generate a new API Token
- Note your API Endpoint (usually
https://your-company.mocoapp.com/api/v1/)
// Basic configuration
$moco = new MocoClient([
'endpoint' => 'https://your-company.mocoapp.com/api/v1/',
'token' => 'your-api-token'
]);
// The endpoint URL will automatically have a trailing slash added if missing- Never commit API tokens to version control
- Use environment variables for sensitive credentials:
// Using environment variables
$moco = new MocoClient([
'endpoint' => $_ENV['MOCO_ENDPOINT'],
'token' => $_ENV['MOCO_TOKEN']
]);- Regenerate tokens regularly
- Limit token permissions to only what your application needs
// Create a new user
$user = $moco->users->create([
'firstname' => 'Alice',
'lastname' => 'Smith',
'email' => 'alice.smith@company.com',
'password' => 'secure-password-123',
'unit_id' => 123456,
'active' => true,
'language' => 'en',
'mobile_phone' => '+1-555-0123',
'tags' => ['developer', 'frontend']
]);
// Get all users
$users = $moco->users->get();
// Get a specific user
$user = $moco->users->get(12345);
// Update user
$updatedUser = $moco->users->update(12345, [
'firstname' => 'Alicia',
'mobile_phone' => '+1-555-0124'
]);
// Get user performance report
$performance = $moco->users->getPerformanceReport(12345, [
'from' => '2024-01-01',
'to' => '2024-12-31'
]);
// Delete user
$moco->users->delete(12345);// Create a company
$company = $moco->companies->create([
'name' => 'Acme Corporation',
'website' => 'https://acme.com',
'currency' => 'USD',
'country_code' => 'US',
'address' => "123 Main St\nAnytown, ST 12345",
'phone' => '+1-555-0199',
'tags' => ['client', 'enterprise']
]);
// Create a contact for the company
$contact = $moco->contacts->create([
'firstname' => 'Jane',
'lastname' => 'Johnson',
'email' => 'jane@acme.com',
'phone' => '+1-555-0198',
'company_id' => $company->id,
'tags' => ['primary-contact']
]);
// Get all companies with pagination
$companies = $moco->companies->get([
'tags' => 'client'
]);// Create a project
$project = $moco->projects->create([
'name' => 'Website Redesign',
'company_id' => 12345,
'user_id' => 67890, // Project leader
'budget' => 50000.00,
'currency' => 'USD',
'start_date' => '2024-01-15',
'finish_date' => '2024-06-30',
'tags' => ['web-development', 'design']
]);
// Create project tasks
$task = $moco->projectTasks->create([
'name' => 'Frontend Development',
'project_id' => $project->id,
'billable' => true,
'active' => true
]);
// Get project details
$projectDetails = $moco->projects->get($project->id);
// Get all tasks for a project
$tasks = $moco->projectTasks->get(['project_id' => $project->id]);
// Update project
$updatedProject = $moco->projects->update($project->id, [
'budget' => 55000.00,
'tags' => ['web-development', 'design', 'responsive']
]);// Log a time entry
$activity = $moco->activities->create([
'date' => '2024-01-16',
'hours' => 6.5,
'description' => 'Implemented user authentication system',
'project_id' => 12345,
'task_id' => 67890,
'user_id' => 11111,
'billable' => true,
'tag' => 'development'
]);
// Get activities for a date range
$activities = $moco->activities->get([
'from' => '2024-01-01',
'to' => '2024-01-31',
'user_id' => 11111
]);
// Update time entry
$updatedActivity = $moco->activities->update($activity->id, [
'hours' => 7.0,
'description' => 'Implemented user authentication system with 2FA'
]);
// Get activities by project
$projectActivities = $moco->activities->get([
'project_id' => 12345
]);// Create an invoice
$invoice = $moco->invoice->create([
'company_id' => 12345,
'project_id' => 67890,
'recipient_address' => "Acme Corporation\n123 Main St\nAnytown, ST 12345",
'date' => '2024-01-30',
'due_date' => '2024-02-29',
'currency' => 'USD',
'tax' => 8.5,
'discount' => 5.0,
'items' => [
[
'type' => 'item',
'title' => 'Website Development',
'quantity' => 1,
'unit' => 'month',
'unit_price' => 5000.00
]
]
]);
// Get invoice payments
$payments = $moco->invoicePayments->get(['invoice_id' => $invoice->id]);
// Add payment to invoice
$payment = $moco->invoicePayments->create([
'invoice_id' => $invoice->id,
'date' => '2024-02-15',
'amount' => 5000.00,
'currency' => 'USD'
]);
// Get all invoices
$invoices = $moco->invoice->get([
'status' => 'paid',
'from' => '2024-01-01',
'to' => '2024-12-31'
]);// Create a deal
$deal = $moco->deal->create([
'name' => 'Enterprise Website Project',
'money' => 75000.00,
'currency' => 'USD',
'reminder_date' => '2024-02-01',
'user_id' => 11111,
'company_id' => 12345,
'status' => 'potential',
'tags' => ['enterprise', 'web-development']
]);
// Create an offer
$offer = $moco->offers->create([
'company_id' => 12345,
'project_id' => 67890,
'recipient_address' => "Acme Corporation\n123 Main St\nAnytown, ST 12345",
'date' => '2024-01-15',
'currency' => 'USD',
'tax' => 8.5,
'discount' => 10.0,
'items' => [
[
'type' => 'title',
'title' => 'Website Development Package'
],
[
'type' => 'description',
'description' => 'Complete website redesign and development'
],
[
'type' => 'item',
'title' => 'Frontend Development',
'quantity' => 120,
'unit' => 'hours',
'unit_price' => 125.00
]
]
]);
// Get deal categories
$dealCategories = $moco->dealCategory->get();The MOCO PHP SDK provides the following services through the main client:
$moco->users- User management and operations$moco->companies- Company management$moco->contacts- Contact management$moco->projects- Project management$moco->projectTasks- Project task management$moco->activities- Time tracking and activities
Access account-related services via $moco->account:
$moco->account->customProperties- Custom field management$moco->account->catalogs- Service catalog management$moco->account->fixedCosts- Fixed cost management$moco->account->hourlyRates- Hourly rate management$moco->account->internalHourlyRates- Internal rate management
$moco->invoice- Invoice management$moco->invoicePayments- Invoice payment tracking$moco->invoiceReminders- Invoice reminder management$moco->offers- Offer/quote management$moco->deal- Deal pipeline management$moco->purchases- Purchase management
$moco->planningEntries- Resource planning$moco->schedules- Schedule management$moco->reports- Report generation
$moco->tags- Tag management$moco->units- Team/unit management$moco->vatCodes- VAT code management$moco->webHooks- Webhook management
All services provide standard CRUD operations where applicable:
// Create a resource
$resource = $service->create(array $data);
// Get all resources (with optional filters)
$resources = $service->get(array $filters = []);
// Get a specific resource by ID
$resource = $service->get(int $id);
// Update a resource
$updated = $service->update(int $id, array $data);
// Delete a resource
$service->delete(int $id);Most services support filtering and pagination:
// Date range filtering
$activities = $moco->activities->get([
'from' => '2024-01-01',
'to' => '2024-01-31'
]);
// Tag filtering
$projects = $moco->projects->get([
'tags' => 'active,web-development'
]);
// Status filtering
$invoices = $moco->invoice->get([
'status' => 'open'
]);The SDK validates required parameters automatically:
try {
$user = $moco->users->create([
'firstname' => 'John'
// Missing required fields: lastname, email, password, unit_id
]);
} catch (Moco\Exception\InvalidRequestException $e) {
echo "Missing required parameters: " . $e->getMessage();
}We welcome contributions to the MOCO PHP SDK, reach out!
The MOCO PHP SDK follows Semantic Versioning (SemVer) for predictable and reliable releases:
- MAJOR: Breaking changes that require code updates
- MINOR: New features that are backwards compatible
- PATCH: Bug fixes and improvements
The MOCO PHP SDK is open-sourced software licensed under the MIT license.