PHPackages                             dealnews/datocms-cma-client - 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. [API Development](/categories/api)
4. /
5. dealnews/datocms-cma-client

ActiveLibrary[API Development](/categories/api)

dealnews/datocms-cma-client
===========================

Unofficial DatoCMS API Client for the Content Management API

0.4.2(1mo ago)01.1k↓23.1%BSD-3-ClausePHPPHP ^8.2CI failing

Since Dec 19Pushed 1mo agoCompare

[ Source](https://github.com/dealnews/datocms-cma-client)[ Packagist](https://packagist.org/packages/dealnews/datocms-cma-client)[ RSS](/packages/dealnews-datocms-cma-client/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (6)Dependencies (12)Versions (16)Used By (0)

datocms-cma-client
==================

[](#datocms-cma-client)

Unofficial DatoCMS API Client for the Content Management API

Usage
-----

[](#usage)

Initialize the client:

```
use DealNews\DatoCMS\CMA\Client;

$client = new Client('', '');
```

### Records/Items

[](#recordsitems)

Get a list of records/items

```
$list = $client->record->list();
```

Get a filtered list of records/items

```
use DealNews\DatoCMS\CMA\Parameters\Record;

$parameters = new Record();
$parameters->filter->ids = ['abcd', 'efgh'];

$list = $client->record->list($parameters);
```

#### Creating and Updating Records

[](#creating-and-updating-records)

You can create/update records in three ways:

**Option 1: Using the Record Input Class with DataTypes**

This approach provides type safety and validation, but it is incomplete. Structured-Text is the big missing piece.

```
use DealNews\DatoCMS\CMA\Input\Record;
use DealNews\DatoCMS\CMA\DataTypes\Scalar;
use DealNews\DatoCMS\CMA\DataTypes\Color;
use DealNews\DatoCMS\CMA\DataTypes\Location;
use DealNews\DatoCMS\CMA\DataTypes\Asset;
use DealNews\DatoCMS\CMA\DataTypes\SEO;

// Create a new record with the item_type_id
$record = new Record('DxMaW10UQiCmZcuuA-IkkA');

// Use Scalar DataType for simple values
$title = Scalar::init()->set('Hello World');
$record->attributes['title'] = $title;

// Or use DataType helper methods for complex types
$color = Color::init()->setColor(255, 128, 64, 200);
$record->attributes['brand_color'] = $color;

$location = Location::init()->setLocation(40.7128, -74.0060);
$record->attributes['coordinates'] = $location;

$asset = Asset::init()->setAsset('upload_123', 'Image Title', 'Alt Text');
$record->attributes['image'] = $asset;

$seo = SEO::init()->setSEO('Page Title', 'Page Description', 'image_id', 'summary', false);
$record->attributes['seo'] = $seo;

// Convert to array and create the record
$result = $client->record->create($record->toArray());
```

**Option 2: Using the Record Input Class with Plain Arrays**

You can use the `Record` class but populate attributes with arrays:

```
use DealNews\DatoCMS\CMA\Input\Record;

$record = new Record('DxMaW10UQiCmZcuuA-IkkA');
$record->attributes = [
    'title' => 'Hello World',
    'body' => 'This is the body',
    'brand_color' => [
        'red' => 255,
        'green' => 128,
        'blue' => 64,
        'alpha' => 200
    ]
];

$result = $client->record->create($record->toArray());
```

**Option 3: Using a Plain Array**

You can still pass a plain array directly:

```
$new_record = [
    'type' => 'item',
    'attributes' => [
        'title' => 'Hello World',
        'body' => 'This is the body'
    ],
    'relationships' => [
        'item_type' => [
            'data' => [
                'type' => 'item_type',
                'id' => 'DxMaW10UQiCmZcuuA-IkkA'
            ],
        ]
    ]
];

$result = $client->record->create($new_record);
```

#### Available DataTypes Classes

[](#available-datatypes-classes)

The library provides the following DataTypes classes for structured field values:

- `Scalar` - For simple string, integer, float, or boolean values
- `Color` - For RGBA color values (red, green, blue, alpha: 0-255)
- `Location` - For geographic coordinates (latitude: -90 to 90, longitude: -180 to 180)
- `Asset` - For file uploads with metadata (upload\_id, title, alt, focal\_point, custom\_data)
- `ExternalVideo` - For external video embeds (YouTube, Vimeo, Facebook)
- `SEO` - For SEO metadata (title, description, image, twitter\_card, no\_index)

All DataTypes support localization via the `addLocale()` method for multilingual content.

---

### Models (Item-Types)

[](#models-item-types)

Models define the content types in your DatoCMS project. The DatoCMS API refers to these as "item-types".

Get a list of models:

```
$models = $client->model->list();
```

Get a specific model by ID:

```
$model = $client->model->retrieve('model-id');
```

Create a new model:

```
use DealNews\DatoCMS\CMA\Input\Model;

$model = new Model();
$model->attributes['name'] = 'Blog Post';
$model->attributes['api_key'] = 'blog_post';
$model->attributes['singleton'] = false;
$model->attributes['sortable'] = true;
$model->attributes['draft_mode_active'] = true;

$result = $client->model->create($model);
```

Update a model:

```
use DealNews\DatoCMS\CMA\Input\Model;

$model = new Model();
$model->attributes['name'] = 'Updated Blog Post';

$result = $client->model->update('model-id', $model);
```

Delete a model:

```
$result = $client->model->delete('model-id');
```

Duplicate a model:

```
$result = $client->model->duplicate('model-id');
```

#### Model Attributes

[](#model-attributes)

Common model attributes include:

AttributeTypeDescription`name`stringHuman-readable name`api_key`stringMachine-friendly key`singleton`boolSingle-instance model`sortable`boolAllow manual record sorting`modular_block`boolIs a block model`tree`boolHierarchical records`draft_mode_active`boolEnable drafts`all_locales_required`boolRequire all locales`ordering_direction`string`asc` or `desc``collection_appearance`string`compact` or `table``hint`stringEditor hint text---

### Uploads

[](#uploads)

The library provides a complete Upload API for managing media assets in DatoCMS.

#### Upload a File

[](#upload-a-file)

The simplest way to upload a file is with the `uploadFile()` helper method:

```
// Upload a local file
$upload = $client->upload->uploadFile('/path/to/image.jpg');

// Upload with metadata
$upload = $client->upload->uploadFile('/path/to/image.jpg', [
    'author'    => 'John Doe',
    'copyright' => '© 2025 Company',
    'notes'     => 'Internal notes about this file',
    'tags'      => ['banner', 'hero', 'featured'],
    'default_field_metadata' => [
        'en' => ['alt' => 'Hero banner image', 'title' => 'Main Banner'],
        'es' => ['alt' => 'Imagen de banner', 'title' => 'Banner Principal'],
    ],
]);

// Upload to a specific collection (folder)
$upload = $client->upload->uploadFile('/path/to/image.jpg', null, 'collection-id');
```

#### Upload from URL

[](#upload-from-url)

Upload a file directly from a remote URL:

```
// Upload from URL
$upload = $client->upload->uploadFromUrl('https://example.com/image.jpg');

// With custom filename and metadata
$upload = $client->upload->uploadFromUrl(
    'https://example.com/image.jpg',
    'custom-filename.jpg',
    ['author' => 'Jane Doe']
);
```

#### List and Filter Uploads

[](#list-and-filter-uploads)

```
use DealNews\DatoCMS\CMA\Parameters\Upload;

$params = new Upload();
$params->filter->type = 'image';           // Filter by type: image, video, audio, etc.
$params->filter->query = 'banner';          // Full-text search
$params->filter->tags = ['hero', 'featured']; // Filter by tags
$params->filter->upload_collection_id = 'collection-123'; // Filter by folder
$params->order_by->addOrderByField('created_at', 'DESC');
$params->page->limit = 25;

$uploads = $client->upload->list($params);
```

#### Upload Collections (Folders)

[](#upload-collections-folders)

Organize uploads into folders:

```
use DealNews\DatoCMS\CMA\Input\UploadCollection;

// List collections
$collections = $client->upload_collection->list();

// Create a collection
$collection = new UploadCollection();
$collection->attributes['label'] = 'Product Images';
$result = $client->upload_collection->create($collection);

// Create a nested collection
$subcollection = new UploadCollection();
$subcollection->attributes['label'] = 'Thumbnails';
$subcollection->parent_id = $result['data']['id'];
$client->upload_collection->create($subcollection);

// Delete a collection
$client->upload_collection->delete($collection_id);
```

#### Upload Tags

[](#upload-tags)

Manage user-defined tags for uploads:

```
// List all tags
$tags = $client->upload_tag->list();

// Create a tag
$tag = $client->upload_tag->create('featured');

// Delete a tag
$client->upload_tag->delete($tag['data']['id']);
```

#### Smart Tags

[](#smart-tags)

List auto-detected smart tags (read-only):

```
$smart_tags = $client->upload_smart_tag->list();
```

#### Bulk Operations

[](#bulk-operations)

```
// Bulk delete uploads
$client->upload->deleteBulk(['upload-1', 'upload-2', 'upload-3']);

// Bulk update metadata
$client->upload->updateBulk(
    ['upload-1', 'upload-2'],
    ['author' => 'Updated Author', 'copyright' => '© 2025']
);
```

#### Manual Upload Flow

[](#manual-upload-flow)

For advanced use cases, you can use the low-level upload flow:

```
use DealNews\DatoCMS\CMA\Input\Upload;

// Step 1: Request upload permission
$request = $client->upload_request->create('image.jpg');
$s3_url = $request['data']['attributes']['url'];
$s3_headers = $request['data']['attributes']['request_headers'];

// Step 2: Upload to S3 (using your own HTTP client)
// PUT $s3_url with file contents and $s3_headers

// Step 3: Register the upload in DatoCMS
$upload = new Upload();
$upload->attributes->path = $request['data']['id'];
$upload->attributes->author = 'John Doe';
$result = $client->upload->create($upload);
```

###  Health Score

43

—

FairBetter than 91% of packages

Maintenance89

Actively maintained with recent releases

Popularity20

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 83.5% 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

Every ~14 days

Total

6

Last Release

53d ago

PHP version history (2 changes)0.1.0PHP ^8.4

0.2.0PHP ^8.2

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/49531?v=4)[Brian Moon](/maintainers/brianlmoon)[@brianlmoon](https://github.com/brianlmoon)

![](https://www.gravatar.com/avatar/dbf067b8b1b679cc96fb0e13483a6be5b90cb35dfbb85d471cee151b9fa87417?d=identicon)[dealnews](/maintainers/dealnews)

![](https://www.gravatar.com/avatar/243758ed7035943299b60b3927056b7bdefb979d7161183261ddc2ac82a53840?d=identicon)[jkearle](/maintainers/jkearle)

---

Top Contributors

[![jearle-dealnews](https://avatars.githubusercontent.com/u/8784094?v=4)](https://github.com/jearle-dealnews "jearle-dealnews (116 commits)")[![brianlmoon](https://avatars.githubusercontent.com/u/49531?v=4)](https://github.com/brianlmoon "brianlmoon (17 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (6 commits)")

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/dealnews-datocms-cma-client/health.svg)

```
[![Health](https://phpackages.com/badges/dealnews-datocms-cma-client/health.svg)](https://phpackages.com/packages/dealnews-datocms-cma-client)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[theodo-group/llphant

LLPhant is a library to help you build Generative AI applications.

1.5k311.5k5](/packages/theodo-group-llphant)[wheelpros/fitment-platform-api

Magento 2 (Open Source)

12.1k1.2k](/packages/wheelpros-fitment-platform-api)[avalara/avataxclient

Client library for Avalara's AvaTax suite of business tax calculation and processing services. Uses the REST v2 API.

517.9M7](/packages/avalara-avataxclient)[alexacrm/dynamics-webapi-toolkit

Web API toolkit for Microsoft Dynamics 365 and Dynamics CRM

81324.1k1](/packages/alexacrm-dynamics-webapi-toolkit)[commercetools/commercetools-sdk

The official PHP SDK for the commercetools Composable Commerce APIs

19281.5k](/packages/commercetools-commercetools-sdk)

PHPackages © 2026

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