Brandfolder PHP SDK

BrandfolderClient
in package

Brandfolder

Client for interacting with the Brandfolder API.

Properties

$default_brandfolder_id : string|null: The Brandfolder to use for Brandfolder-specific requests, when no other Brandfolder is specified.
$default_collection_id : string|null: The Collection to use for Collection-specific requests, when no other Collection is specified.
$default_items_per_page : int: The default number of items to fetch per GET request. Corresponds to the "per" query param.
$message : string: A useful message pertaining to the most recent operation, if applicable.
$status : int: The status code of the most recent operation, if applicable.
$api_key : string: The Brandfolder API key with which to authenticate (used as a bearer token).
$endpoint : string: The REST API endpoint.
$http_client : null|ClientInterface: HTTP client.
$log_data : array<string|int, mixed>: Internal storage for logging/recording data.
$verbose_logging_mode : bool: Flag for enabling verbose logging/recording.

Methods

__construct() : mixed: BrandfolderClient constructor.
addAssetsToLabel() : object|false: Add one or more assets to a Label.
addCustomFieldsToAsset() : bool: Add custom field values to an asset.
clearLogData() : void: Clear log data.
createAsset() : object|false: Create a new Asset.
createAssets() : array<string|int, mixed>|false: Create multiple new Assets in one operation.
createBrandfolderInOrganization() : object|false: Create a new Brandfolder in an Organization.
createCollectionInBrandfolder() : object|false: Create a new Collection in a Brandfolder.
createCustomFieldKeysForBrandfolder() : object|false: Create custom field keys for a Brandfolder.
createInvitation() : object|false: Create a new invitation to an Organization, Brandfolder, Collection, Portal, or Brandguide.
createLabelInBrandfolder() : object|false: Create a new Label in a Brandfolder.
createSectionInBrandfolder() : object|false: Create a new Section in a Brandfolder.
createTagsForAsset() : object|bool: Create Tags for an Asset (i.e. apply Tags to an Asset).
deleteAsset() : bool: Delete an Asset.
deleteAttachment() : bool: Delete an existing attachment.
deleteCollection() : bool: Delete a Collection.
deleteCustomFieldKey() : bool: Delete a custom field key.
deleteCustomFieldValue() : bool: Delete a custom field value.
deleteInvitation() : bool: Delete an invitation.
deleteLabel() : bool: Delete a Label.
deleteTagsOnAsset() : bool: Delete one or more tags associated with a given asset.
deleteUserPermission() : bool: Delete a user permission.
disableVerboseLogging() : void: Deactivate verbose logging mode.
enableVerboseLogging() : void: Activate verbose logging mode.
fetchAsset() : object|false: Fetch an individual Asset.
fetchAttachment() : object|false: Fetch an individual Attachment.
fetchBrandfolder() : object|false: Fetch an individual Brandfolder by ID.
fetchCollection() : object|false: Fetch an individual Collection by ID.
fetchInvitation() : object|false: Fetch an individual invitation by ID.
fetchLabel() : object|false: Fetch an individual Label by ID.
fetchOrganization() : object|false: Fetch a single Organization by ID.
fetchSection() : object|false: Fetch an individual Section by ID.
fetchUserPermission() : object|false: Fetch a user permission by ID.
getAll() : object|false: Helper method for GET requests. Compiles data from all pages of results for a given request into a single object.
getBrandfolders() : object|bool|array<string|int, mixed>: Get all Brandfolders, in one of two formats.
getCollectionsForUser() : object|false: Alternate name for backward compatibility.
getCollectionsInBrandfolder() : array<string|int, mixed>|object|false: Alternate name for backward compatibility.
getLogData() : array<string|int, mixed>: Get log data.
getOrganizations() : object|false: Alternate name for backward compatibility.
getTags() : array<string|int, mixed>|object|false: Retrieves Tags used in a Brandfolder or Collection.
listAllBrandfolderNames() : array<string|int, mixed>|bool: Get an array containing the names of all Brandfolders (to which the current user has access), keyed by Brandfolder ID.
listAllCollectionNamesInBrandfolder() : array<string|int, mixed>|false: Get a simple array of all Collection names in a Brandfolder, keyed by ID.
listAllSectionNamesInBrandfolder() : array<string|int, mixed>|false: Get an array containing the names of all Sections in a Brandfolder, keyed by Section ID.
listAllSectionsInBrandfolder() : object|false: List all Sections in a Brandfolder (combining all pages of results).
listAssets() : object|false: List multiple Assets.
listAssetsInBrandfolder() : object|bool: List Assets in a Brandfolder.
listAssetsInCollection() : object|bool: List Assets in a Collection.
listAssetsInLabel() : object|bool: List Assets in a Label.
listAssetsInOrganization() : object|bool: List Assets in a specific Organization.
listAttachments() : object|bool: List Attachments in a given context/scope (Organization, Brandfolder, Collection, or Asset).
listAttachmentsForAsset() : object|bool: List Attachments for a given Asset.
listAttachmentsForBrandfolder() : object|bool: List Attachments for a given Brandfolder.
listAttachmentsForCollection() : object|bool: List Attachments for a given Collection.
listAttachmentsForOrganization() : object|bool: List Attachments for a given Organization.
listAttachmentsForSection() : object|bool: List Attachments for a given Section.
listBrandfolders() : array<string|int, mixed>|object|false: Gets Brandfolders to which the current user has access.
listCollectionsForUser() : object|false: Lists Collections to which the current user has access.
listCollectionsInBrandfolder() : array<string|int, mixed>|object|false: List Collections belonging to a given Brandfolder.
listCustomFields() : array<string|int, mixed>|object|false: Gets custom field data for a Brandfolder.
listCustomFieldValuesForAsset() : object|false: List custom field values for a given asset.
listInvitations() : object|bool: Lists Invitations to an Organization, Brandfolder, Collection, Portal, or Brandguide.
listLabelsInBrandfolder() : array<string|int, mixed>|false: List Labels defined in a given Brandfolder, structured as a nested associative array.
listOrganizations() : object|false: Gets Brandfolder Organizations to which the current user belongs.
listSectionsInBrandfolder() : object|false: List Sections in a Brandfolder.
listTagsForAsset() : object|bool: List tags for a given asset.
listTagsInBrandfolder() : object|bool: List Tags in a Brandfolder.
listTagsInCollection() : object|bool: List tags in a Collection.
listUserPermissionsForBrandfolder() : object|bool: List user permissions for a Brandfolder.
listUserPermissionsForCollection() : object|bool: List user permissions for a Collection.
listUserPermissionsForOrganization() : object|bool: List user permissions for an Organization.
moveLabel() : object|false: Move a Label to a new parent Label.
request() : object|false: Makes a request to the Brandfolder API, processes the result, and handles any errors that may arise.
setCustomFieldValuesForAssets() : bool|object: Set custom field values for a given custom field, on one or more assets.
updateAsset() : object|false: Update an existing asset.
updateAttachment() : object|false: Update an existing Attachment.
updateCollection() : object|false: Update an existing Collection.
updateCustomFieldKey() : object|false: Update an individual custom field key by ID.
updateCustomFieldValue() : object|false: Update an existing custom field value by value ID
updateLabel() : object|false: Update an existing Label.
updateTag() : object|bool: Update an existing tag. Note: this only updates one particular instance of a tag name. Whenever you create a new tag for an asset, a new ID is created for that instance, even if the tag name is already used elsewhere.
verboseLoggingIsEnabled() : bool: Determine whether verbose logging is enabled.
decorateAsset() : void: Modify an asset object to contain useful values for each included attribute rather than just a list of items with IDs, and to clean up custom field and attachment data.
decorateAttachment() : void: Update an attachment to contain useful values for each included attribute rather than just a list of items with IDs.
formatDateTime() : string: Accept various types of date/time inputs and produce a date/time string in a format suitable for the Brandfolder API.
jsonDecode() : mixed: Compatibility wrapper to support various json-decode methods.
jsonEncode() : false|string: Compatibility wrapper to support various json-encode methods.
log() : void: Add log data.
processRelationships() : void: Restructure an entity to contain useful values for each included attribute rather than just a list of items with IDs that need to be cross-referenced with the "included" data array returned by the API.
processResultData() : void: Improve the usefulness of data returned from GET requests.
restructureIncludedData() : void: Structure included data as an associative array of items grouped by type and indexed therein by ID.

$default_brandfolder_id

The Brandfolder to use for Brandfolder-specific requests, when no other Brandfolder is specified.


        public
            string|null
    $default_brandfolder_id

$default_collection_id

The Collection to use for Collection-specific requests, when no other Collection is specified.


        public
            string|null
    $default_collection_id
     = null

$default_items_per_page

The default number of items to fetch per GET request. Corresponds to the "per" query param.


        public
            int
    $default_items_per_page
     = 100

$message

A useful message pertaining to the most recent operation, if applicable.


        public
            string
    $message
     = ''

$status

The status code of the most recent operation, if applicable.


        public
            int
    $status
     = 0

$api_key

The Brandfolder API key with which to authenticate (used as a bearer token).


        protected
            string
    $api_key

$endpoint

The REST API endpoint.


        protected
            string
    $endpoint
     = 'https://brandfolder.com/api/v4'

$http_client

HTTP client.


        protected
            null|ClientInterface
    $http_client

$log_data

Internal storage for logging/recording data.


        protected
            array<string|int, mixed>
    $log_data
     = []

$verbose_logging_mode

Flag for enabling verbose logging/recording.


        protected
            bool
    $verbose_logging_mode
     = false

__construct()

BrandfolderClient constructor.


    public
                    __construct(string $api_key[, string|null $brandfolder_id = null ][, ClientInterface|null $http_client = null ]) : mixed

Parameters

$api_key : string
$brandfolder_id : string|null = null
$http_client : ClientInterface|null = null

addAssetsToLabel()

Add one or more assets to a Label.


    public
                    addAssetsToLabel(array<string|int, mixed> $asset_ids, string $label) : object|false


 $bf = new BrandfolderClient($api_key);

 $beach_assets_result = $bf->listAssets(['search' => 'beach OR (sand AND surf)']);
 if ($beach_assets_result) {
   $beach_asset_ids = array_map(function($asset) {
     return $asset->id;
   }, $beach_assets_result->data);

   $labeling_result = $bf->addAssetsToLabel($beach_asset_ids, $beach_label_id);
   if ($labeling_result) {
     $num_assets = count($beach_asset_ids);
     echo "$num_assets assets successfully added to Label $beach_label_id. <br/>";
   }
 }

Parameters

$asset_ids : array<string|int, mixed>
$label : string: The ID/key of the Label to which the given assets should be added.

Return values

object|false

addCustomFieldsToAsset()

Add custom field values to an asset.


    public
                    addCustomFieldsToAsset(string $asset_id, array<string|int, mixed> $custom_field_values[, string|null $field_key_type = 'name' ][, string|null $brandfolder_id = null ]) : bool


 $bf = new BrandfolderClient($api_key, $default_brandfolder_id);

 // Example A. Add custom field values to an asset by custom field name.
 $custom_field_values = [
   'eye-color' => 'brown',
   'hair-color' => 'black',
 ];
 $result = $bf->addCustomFieldsToAsset($asset_id, $custom_field_values);

 // Example B. Add custom field values to an asset by custom field ID.
 $custom_field_values = [
   $eye_color_custom_field_id => 'brown',
   $hair_color_custom_field_id => 'black',
 ];
 $result = $bf->addCustomFieldsToAsset($asset_id, $custom_field_values, 'id');

Note: The API endpoint previously used by this method (/custom_field_keys/{custom_field_key_id}/custom_field_values) was seemingly removed on 2023-05-17. This method was then updated to work with the new endpoint/pattern while maintaining backward compatibility.

Parameters

$asset_id : string
$custom_field_values : array<string|int, mixed>: Associative array with key-value pairs. The key should identify the custom field (by name or ID, depending on the $field_key_type param), and the value should be the value you wish to store on the given asset for that field.
$field_key_type : string|null = 'name': If name (default), the $custom_field_values array should be keyed by custom field names (e.g. eye-color). If id, the $custom_field_values array should be keyed by custom field IDs (e.g. h3689xgmx2jx558xxnt16xp). Note: name mode is more convenient, but (a) requires an extra API call to look up the custom field IDs, and (b) can cause functionality to break if you are invoking this method with a hard-coded name and the custom field's name is subsequently changed.
$brandfolder_id : string|null = null: The ID of the Brandfolder in which the asset resides. If not provided, we will attempt to use the default Brandfolder if one is defined. This is only necessary if using the name option for $field_key_type.

Return values

bool —

true if all requests on success, false otherwise.

clearLogData()

Clear log data.


    public
                    clearLogData() : void

createAsset()

Create a new Asset.


    public
                    createAsset(string $name, array<string|int, mixed> $attachments, string $section[, string|null $description = null ][, string|null $brandfolder = null ][, string|null $collection = null ][, string|int|DateTime|null $availability_start = null ][, string|int|DateTime|null $availability_end = null ]) : object|false


$bf = new BrandfolderClient($api_key);

$attachments = [
  [
    'url' => 'https://example.com/image-01.jpg',
    'filename' => 'image-01.jpg',
  ],
  [
    'url' => 'https://example.com/image-02.jpg',
    'filename' => 'image-02.jpg',
  ],
];
$result = $bf->createAsset('My New Asset', $attachments, '$existing_section_key', 'A description of the asset.');
if ($result) {
  $new_asset = $result->data[0];
  echo "New Asset created: {$new_asset->attributes->name} ({$new_asset->id}) <br/>";
}

Parameters

$name : string
$attachments : array<string|int, mixed>
$section : string
$description : string|null = null
$brandfolder : string|null = null
$collection : string|null = null
$availability_start : string|int|DateTime|null = null: This can be a date/time string, a timestamp, or a DateTime object.
$availability_end : string|int|DateTime|null = null: This can be a date/time string, a timestamp, or a DateTime object.

Return values

object|false

createAssets()

Create multiple new Assets in one operation.


    public
                    createAssets(array<string|int, mixed> $assets, string $section[, string|null $brandfolder = null ][, string|null $collection = null ]) : array<string|int, mixed>|false


$bf = new BrandfolderClient($api_key);

$assets = [
  [
    'name' => 'My New Asset 1',
    'description' => 'The first asset.',
    'availability_start' => 'tomorrow',
    'attachments' => [
      [
        'url' => 'https://example.com/image-01.jpg',
        'filename' => 'image-01.jpg',
      ]
    ],
  ],
  [
    'name' => 'My New Asset 2',
    'description' => 'The second asset.',
    'availability_end' => '2025-12-31',
    'attachments' => [
      [
        'url' => 'https://example.com/image-02.jpg',
        'filename' => 'image-02.jpg',
      ]
    ],
  ],
];
$result = $bf->createAssets($assets, $existing_section_key);
if ($result) {
  echo "New assets created: <br/>";
  foreach ($result as $new_asset) {
    echo "&nbsp; {$new_asset->attributes->name} ({$new_asset->id}) <br/>";
  }
}

Parameters

$assets : array<string|int, mixed>: Array of arrays with asset data. Each asset data array should consist of: name (string), description (optional string), availability_start (optional string|int|DateTime), availability_end (optional string|int|DateTime), attachments (array), consisting of: url (string), filename (string)
$section : string
$brandfolder : string|null = null
$collection : string|null = null

Return values

array<string|int, mixed>|false

createBrandfolderInOrganization()

Create a new Brandfolder in an Organization.


    public
                    createBrandfolderInOrganization(string $organization_id, string $name[, string|null $tagline = null ][, string $privacy = 'private' ][, string|null $slug = null ]) : object|false


$bf = new BrandfolderClient($api_key);

$result = $bf->createBrandfolderInOrganization($organization_id, 'My Brandfolder',
 'You expected this - Brandfolder's Brandfolder!', 'public');
if ($result) {
  $new_brandfolder = $result->data;
  echo "New Brandfolder created: {$new_brandfolder->attributes->name} ({$new_brandfolder->id}) <br/>";
}

Parameters

$organization_id : string
$name : string
$tagline : string|null = null: A descriptive subtitle/short description of the Brandfolder.
$privacy : string = 'private': The privacy setting for the new Brandfolder. Valid options are "private" (the default) and "public."
$slug : string|null = null: String of letters, numbers, hyphens, and underscores. Note: we recommend not to invent your own slug. If it is not valid, the request will fail with a 422 error. Default is to automatically assign a slug based on $name (a name of "My Brandfolder" would make a slug of "my-brandfolder"). If the provided slug is valid but not unique, it will have a number appended to make it unique.

Return values

object|false

createCollectionInBrandfolder()

Create a new Collection in a Brandfolder.


    public
                    createCollectionInBrandfolder(string $name[, string|null $brandfolder_id = null ][, string|null $tagline = null ][, string|null $slug = null ]) : object|false


$bf = new BrandfolderClient($api_key);

$result = $bf->createCollectionInBrandfolder('My Collection', $brandfolder_id,
 'The best collection ever!', 'my-coll');
if ($result) {
 $new_collection = $result->data;
 echo "New Collection created: {$new_collection->attributes->name} ({$new_collection->id}) <br/>";
}

Parameters

$name : string
$brandfolder_id : string|null = null: The ID of the Brandfolder in which to create the Collection. If not provided, we will attempt to use the default Brandfolder, if defined.
$tagline : string|null = null: A descriptive subtitle/short description of the Collection.
$slug : string|null = null: String of letters, numbers, hyphens, and underscores. Note: we recommend not to invent your own slug. If it is not valid, the request will fail with a 422 error. Default is to automatically assign a slug based on $name (a name of My Collection would make a slug of my-collection). If the provided slug is valid but not unique, it will have a number appended to make it unique.

Return values

object|false

createCustomFieldKeysForBrandfolder()

Create custom field keys for a Brandfolder.


    public
                    createCustomFieldKeysForBrandfolder(array<string|int, mixed> $custom_field_data[, string|null $brandfolder_id = null ]) : object|false

This is only needed for setting up controlled Custom Fields. If this feature is enabled for your Brandfolder, you can set the allowed keys and optionally restrict their allowed values for Custom Fields using this method.


$bf = new BrandfolderClient($api_key);

$custom_fields = [
  // Controlled custom field (allowed values are restricted).
  [
    'name' => 'favorite_coffee',
    'allowed_values' => [
      'Peruvian',
      'Colombian',
      'Ethiopian',
      'Sumatran',
      'Global Blend',
    ]
  ],
  // Uncontrolled custom field (any string value is allowed).
  [
    'name' => 'vortex_strength'
  ]
];
$result = $bf->createCustomFieldKeysForBrandfolder($custom_fields, $brandfolder_id);

Parameters

$custom_field_data : array<string|int, mixed>

An array of associative arrays - one for each new custom field. Each associative array should have the following structure:

name: Required. The name of the custom field [key].
allowed_values: Optional. The value that can be used with this key when creating or updating any Custom Field on an Asset must be one of these strings. If not included or empty array [], the values are not restricted.

$brandfolder_id : string|null = null

The ID of the Brandfolder in which to create the custom field keys. If not provided, we will attempt to use the default Brandfolder if one is defined.

Return values

object|false

createInvitation()

Create a new invitation to an Organization, Brandfolder, Collection, Portal, or Brandguide.


    public
                    createInvitation(string $entity_type, string $entity_id, string $email, string $permission_level[, string $personal_message = '' ][, bool $prevent_email = false ]) : object|false


$bf = new BrandfolderClient($api_key);

$invitee_email = '[email protected]';
$result = $bf->createInvitation('brandfolder', 'brandfolder-id-abc-123', $invitee_email,
 'collaborator', 'Join us!');

if ($result) {
 echo "Invitation sent to $invitee_email.";
}

Parameters

$entity_type : string: The type of entity to which you are inviting the user. Valid values are: organization, brandfolder, collection, portal, and brandguide.
$entity_id : string: The ID of the entity to which you are inviting the user.
$email : string: The email address to which the invitation should be sent.
$permission_level : string: The permission level to be granted to the invitee. Valid values are: guest, collaborator, admin, and owner. Note: owner is only valid when inviting someone to an Organization.
$personal_message : string = '': An optional message to include in the invitation email.
$prevent_email : bool = false: If true, the invitation email will not be sent.

Return values

object|false

createLabelInBrandfolder()

Create a new Label in a Brandfolder.


    public
                    createLabelInBrandfolder(string $name[, string|null $brandfolder_id = null ][, string|null $parent_id = null ]) : object|false


$bf = new BrandfolderClient($api_key);
$result = $bf->createLabelInBrandfolder('My New Label', $brandfolder_id, $parent_id);
if ($result) {
  $new_label = $result->data;
  echo "New Label created: {$new_label->attributes->name} ({$new_label->id}) <br/>";
}

Parameters

$name : string: The name of the Label.
$brandfolder_id : string|null = null: The ID of the Brandfolder in which to create the Label. If not provided, we will attempt to use the default Brandfolder if one is defined.
$parent_id : string|null = null: The ID/key of the parent Label, if any. If provided, the new Label will be nested beneath the parent Label. Otherwise, it will be placed at the top level.

Return values

object|false

createSectionInBrandfolder()

Create a new Section in a Brandfolder.


    public
                    createSectionInBrandfolder(string $name[, string|null $default_asset_type = 'GenericFile' ][, string|null $brandfolder_id = null ][, int|null $position = null ]) : object|false


$bf = new BrandfolderClient($api_key);

$result = $bf->createSectionInBrandfolder('My New Section', 'GenericFile', $brandfolder_id, 2);
if ($result) {
  $new_section = $result->data;
  echo "New Section created: {$new_section->attributes->name} ({$new_section->id}) <br/>";
}

Parameters

$name : string: The name of the Section.
$default_asset_type : string|null = 'GenericFile': Options are GenericFile, Color, Font, ExternalMedium, Person, Press, and Text. Defaults to GenericFile. Note: we strongly recommend using GenericFile when Assets will be added to the Section via the API.
$brandfolder_id : string|null = null: The ID of the Brandfolder in which to create the Section. If not provided, we will attempt to use the default Brandfolder if one is defined.
$position : int|null = null: This is where the new Section is displayed relative to other Sections. Defaults to the last position. 0 means it will be first.

Return values

object|false

createTagsForAsset()

Create Tags for an Asset (i.e. apply Tags to an Asset).


    public
                    createTagsForAsset(string $asset_id, array<string|int, mixed> $tag_names) : object|bool


 $bf = new BrandfolderClient($api_key);

 $tag_names = ['Inferno', 'Relativity', 'Cake'];
 $result = $bf->createTagsForAsset($asset_id, $tag_names);
 if ($result) {
   echo "Asset $asset_id successfully tagged with three tags.";
 }

Parameters

$asset_id : string
$tag_names : array<string|int, mixed>: An array of strings, where each one is the textual name of a Tag to apply to the Asset. These do not need to have been defined anywhere else previously.

Return values

object|bool

deleteAsset()

Delete an Asset.


    public
                    deleteAsset(string $asset_id) : bool


 $bf = new BrandfolderClient($api_key);

 $result = $bf->deleteAsset($asset_id);
 if ($result) {
   echo "Asset $asset_id was successfully deleted. <br/>";
 }

Parameters

$asset_id : string

Return values

bool —

true if successfully deleted, false otherwise.

deleteAttachment()

Delete an existing attachment.


    public
                    deleteAttachment(string $attachment_id) : bool


$bf = new BrandfolderClient($api_key);
$result = $bf->deleteAttachment($attachment_id);
if ($result) {
  echo "Attachment $attachment_id was successfully deleted.";
}

Parameters

$attachment_id : string

Return values

bool —

true on successful deletion. false on failure.

deleteCollection()

Delete a Collection.


    public
                    deleteCollection(string $collection_id) : bool


$bf = new BrandfolderClient($api_key);
$result = $bf->deleteCollection($collection_id);
if ($result) {
  echo "Collection $collection_id deleted successfully. <br/>";
}

Parameters

$collection_id : string

Return values

bool

deleteCustomFieldKey()

Delete a custom field key.


    public
                    deleteCustomFieldKey(string $custom_field_key_id) : bool

Caution: be very careful when using this method, as it also deletes all associated values for the given key.


$bf = new BrandfolderClient($api_key);
$result = $bf->deleteCustomFieldKey($custom_field_key_id);
if ($result) {
  echo "Custom field key $custom_field_key_id was successfully deleted. <br/>";
}

Parameters

$custom_field_key_id : string

Return values

bool —

true if the custom field key was successfully deleted.

deleteCustomFieldValue()

Delete a custom field value.


    public
                    deleteCustomFieldValue(string $custom_field_value_id) : bool

Parameters

$custom_field_value_id : string

Return values

bool —

true on successful deletion, false otherwise.

deleteInvitation()

Delete an invitation.


    public
                    deleteInvitation(string $invitation_id) : bool


$bf = new BrandfolderClient($api_key);

$result = $bf->deleteInvitation($invitation_id);
if ($result) {
 echo "Invitation $invitation_id successfully deleted.";
}

Parameters

$invitation_id : string

Return values

bool —

true if the invitation was deleted successfully, false otherwise.

deleteLabel()

Delete a Label.


    public
                    deleteLabel(string $label_id) : bool


$bf = new BrandfolderClient($api_key);
$result = $bf->deleteLabel($label_id);
if ($result) {
  echo "Label $label_id was successfully deleted. <br/>";
}

Parameters

$label_id : string

Return values

bool

deleteTagsOnAsset()

Delete one or more tags associated with a given asset.


    public
                    deleteTagsOnAsset(string $asset_id, array<string|int, mixed> $tag_names) : bool


 $bf = new BrandfolderClient($api_key);

 $tag_names = ['Inferno', 'Relativity'];
 $result = $bf->deleteTagsOnAsset($asset_id, $tag_names);
 if ($result) {
   echo "Tags successfully removed from asset $asset_id.";
 }

Parameters

$asset_id : string
$tag_names : array<string|int, mixed>

Return values

bool —

true on successful deletion, false otherwise.

deleteUserPermission()

Delete a user permission.


    public
                    deleteUserPermission(string $user_permission_id) : bool

Note: you may receive a "403: access denied" response if you attempt to delete a permission for the same user whose API key is being used to make the request.


$bf = new BrandfolderClient($api_key);

$result = $bf->deleteUserPermission($user_permission_id);
if ($result) {
 echo "User permission $user_permission_id successfully deleted.";
}

Parameters

$user_permission_id : string

Return values

bool —

true if the user permission was deleted successfully; false otherwise.

disableVerboseLogging()

Deactivate verbose logging mode.


    public
                    disableVerboseLogging() : void

enableVerboseLogging()

Activate verbose logging mode.


    public
                    enableVerboseLogging() : void

fetchAsset()

Fetch an individual Asset.


    public
                    fetchAsset(string $asset_id[, array<string|int, mixed>|null $query_params = [] ]) : object|false


$bf = new BrandfolderClient($api_key);

// Example A. Get standard asset data.
$result = $bf->fetchAsset($asset_id);
if ($result) {
  $asset = $result->data;
  echo "Asset: {$asset->attributes->name} ({$asset->id}) <br />";
  echo "&nbsp; Description: {$asset->attributes->description} <br />";
  echo "&nbsp; Thumbnail: <img src=\"{$asset->attributes->thumbnail_url}\" /> <br />";
}

// Example B. Get asset data with CDN URL and attachments.
$result = $bf->fetchAsset($asset_id, ['fields' => 'cdn_url', 'include' => 'attachments']);
if ($result) {
  $asset = $result->data;
  echo "Asset: {$asset->attributes->name} ({$asset->id}) <br />";
  echo "&nbsp; Default CDN Image: <img src=\"{$asset->attributes->cdn_url}\" /> <br />";
  if (!empty($asset->attachments)) {
    foreach ($asset->attachments as $attachment) {
      echo "&nbsp; Attachment: {$attachment->filename} ({$attachment->id}) <br />";
    }
  }
}

Parameters

$asset_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|false

fetchAttachment()

Fetch an individual Attachment.


    public
                    fetchAttachment(string $attachment_id[, array<string|int, mixed>|null $params = [] ]) : object|false


$bf = new BrandfolderClient($api_key);
$result = $bf->fetchAttachment($attachment_id, ['fields' => 'cdn_url']);
if ($result) {
  $attachment = $result->data;
  echo "Attachment: {$attachment->attributes->filename} ({$attachment->id}) <br />";
  echo "&nbsp; CDN URL: {$attachment->attributes->cdn_url} <br />";
  echo "&nbsp; File size (in bytes): " . $attachment->attributes->size . " <br />";
}

Parameters

$attachment_id : string
$params : array<string|int, mixed>|null = []

Return values

object|false

fetchBrandfolder()

Fetch an individual Brandfolder by ID.


    public
                    fetchBrandfolder(string $brandfolder_id[, array<string|int, mixed>|null $query_params = [] ]) : object|false


$bf = new BrandfolderClient($api_key);

$result = $bf->fetchBrandfolder($brandfolder_id, ['include' => 'sections']);
if ($result) {
  $brandfolder = $result->data;
  echo "{$brandfolder->attributes->name} ({$brandfolder->id}) <br/>";
  if (!empty($brandfolder->sections)) {
    foreach ($brandfolder->sections as $section_id => $section) {
      echo "&nbsp; {$section->name} ($section_id) <br/>";
    }
  }
}

Parameters

$brandfolder_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|false

fetchCollection()

Fetch an individual Collection by ID.


    public
                    fetchCollection(string $collection_id[, array<string|int, mixed>|null $query_params = [] ]) : object|false


$bf = new BrandfolderClient($api_key);

$result = $bf->fetchCollection($collection_id, ['include' => 'brandfolder']);
if ($result) {
  $collection = $result->data;
  echo "{$collection->attributes->name} ({$collection->id}) <br/>";
  if (!empty($collection->brandfolders)) {
    $brandfolder = reset($collection->brandfolders);
    echo "&nbsp; Brandfolder: {$brandfolder->name} ({$brandfolder->id}) <br/>";
  }
}

Parameters

$collection_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|false

fetchInvitation()

Fetch an individual invitation by ID.


    public
                    fetchInvitation(string $invitation_id[, array<string|int, mixed>|null $query_params = [] ]) : object|false


$bf = new BrandfolderClient($api_key);

$invitation_result = $bf->fetchInvitation($invitation_id);
if ($invitation_result) {
 $invite = $invitation_result->data;
  echo "Invitation {$invite->id}: {$invite->attributes->email} ({$invite->attributes->permission_level}) <br/>";
}

Parameters

$invitation_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|false

fetchLabel()

Fetch an individual Label by ID.


    public
                    fetchLabel(string $label_id) : object|false


$bf = new BrandfolderClient($api_key);

$result = $bf->fetchLabel($label_id);
if ($result) {
  $label = $result->data;
  echo "Label: {$label->attributes->name} ({$label->id}) <br/>";
}

Parameters

$label_id : string

Return values

object|false

fetchOrganization()

Fetch a single Organization by ID.


    public
                    fetchOrganization(string $organization_id[, array<string|int, mixed> $query_params = [] ]) : object|false


$bf = new BrandfolderClient($api_key);
$org = $bf->fetchOrganization(['include' => 'brandfolders']);

if ($org) {
  echo "{$org->attributes->name} ({$org->attributes->id}) <br/>";
  if (!empty($org->brandfolders)) {
    foreach ($org->brandfolders as $brandfolder_id => $brandfolder) {
      echo "&nbsp; {$brandfolder->name} ($brandfolder_id) <br/>";
    }
  }
}

Parameters

$organization_id : string
$query_params : array<string|int, mixed> = []

Return values

object|false

fetchSection()

Fetch an individual Section by ID.


    public
                    fetchSection(string $section_id[, array<string|int, mixed>|null $query_params = [] ]) : object|false


$bf = new BrandfolderClient($api_key);

$result = $bf->fetchSection($section_id, ['include' => 'brandfolder']);
if ($result) {
 $section = $result->data;
 echo "{$section->attributes->name} ({$section->id}) <br/>";
 if (!empty($section->brandfolders)) {
   $brandfolder = reset($section->brandfolders);
   echo "&nbsp; Brandfolder: {$brandfolder->name} ({$brandfolder->id}). Slug: {$brandfolder->slug}. <br/>";
 }
}

Parameters

$section_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|false

fetchUserPermission()

Fetch a user permission by ID.


    public
                    fetchUserPermission(string $user_permission_id) : object|false


$bf = new BrandfolderClient($api_key);

$permission_result = $bf->fetchUserPermission($user_permission_id);
if ($permission_result) {
  $user = reset($permission_result->data->users);
  echo "Permission {$permission_result->data->id}: {$user->first_name} {$user->last_name} ({$user->email}) "
     . "has permission level {$permission_result->data->attributes->permission_level} <br/>";
}

Parameters

$user_permission_id : string

Return values

object|false

getAll()

Helper method for GET requests. Compiles data from all pages of results for a given request into a single object.


    public
                    getAll(string $path[, array<string|int, mixed> $query_params = [] ]) : object|false

Note: Use with caution. Using this method with endpoints that return a large number of results can be resource-intensive.

Parameters

$path : string
$query_params : array<string|int, mixed> = []

Return values

object|false —

Object containing aggregated response data for successful requests. This will always include a data array, and, where applicable, an included array with supplementary data. false on failure.

getBrandfolders()

Get all Brandfolders, in one of two formats.


    public
                    getBrandfolders([array<string|int, mixed> $query_params = [] ][, bool $simple_format = true ]) : object|bool|array<string|int, mixed>

Use listBrandfolders() or listAllBrandfolderNames() instead.

Parameters

$query_params : array<string|int, mixed> = []
$simple_format : bool = true

Return values

object|bool|array<string|int, mixed>

getCollectionsForUser()

Alternate name for backward compatibility.


    public
                    getCollectionsForUser([array<string|int, mixed> $query_params = [] ]) : object|false

Use listCollectionsForUser() instead.

Parameters

$query_params : array<string|int, mixed> = []

Return values

object|false

getCollectionsInBrandfolder()

Alternate name for backward compatibility.


    public
                    getCollectionsInBrandfolder([string $brandfolder_id = null ][, array<string|int, mixed> $query_params = [] ][, bool $simple_format = true ]) : array<string|int, mixed>|object|false

Use listCollectionsInBrandfolder() or listAllCollectionNamesInBrandfolder() instead.

Parameters

$brandfolder_id : string = null
$query_params : array<string|int, mixed> = []
$simple_format : bool = true

Return values

array<string|int, mixed>|object|false

getLogData()

Get log data.


    public
                    getLogData() : array<string|int, mixed>

Return values

array<string|int, mixed>

getOrganizations()

Alternate name for backward compatibility.


    public
                    getOrganizations([array<string|int, mixed> $query_params = [] ]) : object|false

Use listOrganizations() instead.

Parameters

$query_params : array<string|int, mixed> = []

Return values

object|false

getTags()

Retrieves Tags used in a Brandfolder or Collection.


    public
                    getTags([array<string|int, mixed>|null $query_params = [] ][, string|null $collection = null ][, bool $should_return_data_only = true ]) : array<string|int, mixed>|object|false

This is provided mainly for backward compatibility. Consider using other Tag listing methods.

Parameters

$query_params : array<string|int, mixed>|null = []
$collection : string|null = null: ID of a Collection. If provided, only fetch Tags associated with that Collection.
$should_return_data_only : bool = true: If true, return only the data array nested within the API response. If false, return the entire response object. Defaults to true (data array only) for backward compatibility.

Return values

array<string|int, mixed>|object|false —

On success, returns an array of Tag items (if $should_return_data_only is true), or an object containing such an array plus a meta array with pagination data. false on failure.

listAllBrandfolderNames()

Get an array containing the names of all Brandfolders (to which the current user has access), keyed by Brandfolder ID.


    public
                    listAllBrandfolderNames() : array<string|int, mixed>|bool


$bf = new BrandfolderClient($api_key);
$brandfolders = $bf->listAllBrandfolderNames();

if ($brandfolders) {
  foreach ($brandfolders as $brandfolder_id => $brandfolder_name) {
    echo "{$brandfolder_name} ({$brandfolder_id}) <br/>";
  }
}

Return values

array<string|int, mixed>|bool

listAllCollectionNamesInBrandfolder()

Get a simple array of all Collection names in a Brandfolder, keyed by ID.


    public
                    listAllCollectionNamesInBrandfolder([string|null $brandfolder_id = null ]) : array<string|int, mixed>|false


$bf = new BrandfolderClient($api_key);

$collections = $bf->listAllCollectionNamesInBrandfolder($brandfolder_id);
echo "Collections in Brandfolder: <br/>";
if ($collections) {
  foreach ($collections as $collection_id => $collection_name) {
    echo "{$collection_name} ({$collection_id}) <br/>";
  }
}

Parameters

$brandfolder_id : string|null = null: The ID of the Brandfolder from which to list Collections. If not provided, we will attempt to use the default Brandfolder, if defined.

Return values

array<string|int, mixed>|false

listAllSectionNamesInBrandfolder()

Get an array containing the names of all Sections in a Brandfolder, keyed by Section ID.


    public
                    listAllSectionNamesInBrandfolder([string|null $brandfolder_id = null ]) : array<string|int, mixed>|false


$bf = new BrandfolderClient($api_key);

echo "Sections in Brandfolder: <br/>";
$sections = $bf->listAllSectionNamesInBrandfolder($brandfolder_id);
if ($sections) {
  foreach ($sections as $section_id => $section_name) {
    echo "{$section_name} ({$section_id}) <br/>";
  }
}

Parameters

$brandfolder_id : string|null = null: The ID of the Brandfolder from which to list Sections. If not provided, we will attempt to use the default Brandfolder, if defined.

Return values

array<string|int, mixed>|false

listAllSectionsInBrandfolder()

List all Sections in a Brandfolder (combining all pages of results).


    public
                    listAllSectionsInBrandfolder([string|null $brandfolder_id = null ]) : object|false


$bf = new BrandfolderClient($api_key);

$sections = $bf->listAllSectionsInBrandfolder($brandfolder_id);
if ($sections) {
  foreach ($sections->data as $section) {
    echo "{$section->attributes->name} ({$section->id}). Default asset type: "
     . "{$section->attributes->default_asset_type} <br/>";
  }
}

Parameters

$brandfolder_id : string|null = null: The ID of the Brandfolder from which to list Sections. If not provided, we will attempt to use the default Brandfolder, if defined.

Return values

object|false

listAssets()

List multiple Assets.


    public
                    listAssets([array<string|int, mixed>|null $query_params = [] ][, string|null $collection = null ][, bool $should_get_all = false ]) : object|false

Parameters

$query_params : array<string|int, mixed>|null = []
$collection : string|null = null: An ID of a Collection within which to search for Assets, or all to look throughout the entire Brandfolder. If this param is null, the operation will use the previously defined default Collection, if applicable.
$should_get_all : bool = false: if true, retrieve all applicable assets - i.e. aggregate results from all pages of results. If false, the page size and number will be dictated by the params provided in $query_params (page, and per). If those are not provided, the default behavior will be to return the first page of results.

Return values

object|false

listAssetsInBrandfolder()

List Assets in a Brandfolder.


    public
                    listAssetsInBrandfolder(string $brandfolder_id[, array<string|int, mixed>|null $query_params = [] ]) : object|bool


 $bf = new BrandfolderClient($api_key);

 $assets_result = $bf->listAssetsInBrandfolder($brandfolder_id, ['per' => 150]);
 if ($assets_result) {
   foreach ($assets_result->data as $asset) {
     echo "Asset: {$asset->attributes->name} ({$asset->id}) <br/>";
   }
 }

Parameters

$brandfolder_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

listAssetsInCollection()

List Assets in a Collection.


    public
                    listAssetsInCollection(string $collection_id[, array<string|int, mixed>|null $query_params = [] ]) : object|bool


 $bf = new BrandfolderClient($api_key);

 $assets_result = $bf->listAssetsInCollection($collection_id);
 if ($assets_result) {
   foreach ($assets_result->data as $asset) {
     echo "Asset: {$asset->attributes->name} ({$asset->id}) <br/>";
   }
 }

Parameters

$collection_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

listAssetsInLabel()

List Assets in a Label.


    public
                    listAssetsInLabel(string $label_id[, array<string|int, mixed>|null $query_params = [] ]) : object|bool


 $bf = new BrandfolderClient($api_key);

 $assets_result = $bf->listAssetsInLabel($label_id);
 if ($assets_result) {
   foreach ($assets_result->data as $asset) {
     echo "Asset: {$asset->attributes->name} ({$asset->id}) <br/>";
   }
 }

Parameters

$label_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

listAssetsInOrganization()

List Assets in a specific Organization.


    public
                    listAssetsInOrganization(string $organization_id[, array<string|int, mixed>|null $query_params = [] ]) : object|bool

If you need to fetch all assets within an Organization you should instead do the following: list all Brandfolders (along with the linked Organization for each); iteratively list Assets for each of those Brandfolders that belong to the target Organization (see code example below).


 $bf = new BrandfolderClient($api_key);

 $all_org_assets = [];
 $all_brandfolders = $bf->listBrandfolders(['include' => 'organization']);
 foreach ($all_brandfolders->data as $brandfolder) {
   if (!empty($brandfolder->organizations)) {
     $organization = reset($brandfolder->organizations);
     if ($organization->id == $my_org_id) {
       $assets = $bf->listAssetsInBrandfolder($brandfolder->id);
       if ($assets) {
         $all_org_assets = array_merge($all_org_assets, $assets->data);
       }
     }
   }
 }

Warning: this method will have longer response times than other asset fetch methods. If possible, use listAssetsInBrandfolder() or listAssetsInCollection().

Parameters

$organization_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

listAttachments()

List Attachments in a given context/scope (Organization, Brandfolder, Collection, or Asset).


    public
                    listAttachments(string $context, string $context_id[, array<string|int, mixed>|null $query_params = [] ]) : object|bool


 $bf = new BrandfolderClient($api_key);
 $query_params = [
   'include' => 'asset',
   'fields' => 'cdn_url',
 ];
 $attachments = $bf->listAttachments('brandfolder', $brandfolder_id, $query_params);

Sample Data for $attachments:


  {
    "data": [
      0 => {
        "id": "attachment-id-abc-123",
        "type": "attachments",
        "attributes": {
          "filename": "example.jpg",
          "url": "https://assets2.brandfolder.io/bf-bou-prod/attachment-id-abc-123/v/12345/original/example.jpg",
          "cdn_url": "https://cdn.bfldr.com/DEFG123/at/attachment-id-abc-123/example.jpg?auto=webp&format=png",
          "thumbnail_url": "https://thumbs.bfldr.com/at/attachment-id-abc-123?expiry=1720620621&fit=bounds&height=162&sig=LONGSIGNATURE%3D%3D&width=262",
          "size": 123456,
          ...
        },
        "relationships": {
          "asset": {
            "data": {
              "id": "asset-id-abc-123",
              "type": "generic_files"
            }
          }
        },
        "generic_files": [
          "asset-id-abc-123": {
            "id": "asset-id-abc-123",
            "name": "Example JPG Asset",
            "approved": true,
            "thumbnail_url": "https://thumbs.bfldr.com/as/asset-id-abc-123?expiry=1720620621&fit=bounds&height=162&sig=LONGSIGNATURE%3D%3D&width=262",
            ...
          }
        ]
      },
      ...
    ],
    "included": [
      "generic_files": [
        "asset-id-abc-123": {
          "id": "asset-id-abc-123",
          "name": "Example JPG Asset",
          "approved": true,
          "thumbnail_url": "https://thumbs.bfldr.com/as/asset-id-abc-123?expiry=1720620621&fit=bounds&height=162&sig=LONGSIGNATURE%3D%3D&width=262",
          ...
        },
        "asset-id-def-456": {
          "id": "asset-id-def-456",
          "name": "Another Asset Linked to A Different Attachment",
          "approved": true,
          "thumbnail_url": "https://thumbs.bfldr.com/as/asset-id-def-456?expiry=1720620621&fit=bounds&height=162&sig=LONGSIGNATURE%3D%3D&width=262",
          ...
        },
        ...
      ]
    ]
  }

Parameters

$context : string: The type of entity for which to list attachments. Valid values are: organization, brandfolder, collection, asset. Note: organization is being deprecated. If you need to fetch attachments across an entire Org, you can: (1) list all Brandfolders (include=organization), then (2) list all Sections within each of those Brandfolders that belongs to the relevant Org, then (3) list all Attachments within each of those Sections.
$context_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

listAttachmentsForAsset()

List Attachments for a given Asset.


    public
                    listAttachmentsForAsset(string $asset_id[, array<string|int, mixed>|null $query_params = [] ]) : object|bool


 $bf = new BrandfolderClient($api_key);

 $attachments_result = $bf->listAttachmentsForAsset($asset_id);
 if ($attachments_result) {
   foreach ($attachments_result->data as $attachment) {
     echo "Attachment: {$attachment->attributes->filename} ({$attachment->id}) <br/>";
   }
 }

Parameters

$asset_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

listAttachmentsForBrandfolder()

List Attachments for a given Brandfolder.


    public
                    listAttachmentsForBrandfolder(string $brandfolder_id[, array<string|int, mixed>|null $query_params = [] ]) : object|bool


 $bf = new BrandfolderClient($api_key);

 $attachments_result = $bf->listAttachmentsForBrandfolder($brandfolder_id);
 if ($attachments_result) {
   foreach ($attachments_result->data as $attachment) {
     echo "Attachment: {$attachment->attributes->filename} ({$attachment->id}) <br/>";
   }
 }

Parameters

$brandfolder_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

listAttachmentsForCollection()

List Attachments for a given Collection.


    public
                    listAttachmentsForCollection(string $collection_id[, array<string|int, mixed>|null $query_params = [] ]) : object|bool


 $bf = new BrandfolderClient($api_key);

 $attachments_result = $bf->listAttachmentsForCollection($collection_id);
 if ($attachments_result) {
   foreach ($attachments_result->data as $attachment) {
     echo "Attachment: {$attachment->attributes->filename} ({$attachment->id}) <br/>";
   }
 }

Parameters

$collection_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

listAttachmentsForOrganization()

List Attachments for a given Organization.


    public
                    listAttachmentsForOrganization(string $organization_id[, array<string|int, mixed>|null $query_params = [] ]) : object|bool

If you need to fetch Attachments across an entire Org, you can: (1) list all Brandfolders (include=organization), then (2) list all Sections within each of those Brandfolders that belongs to the relevant Org, then (3) list all Attachments within each of those Sections.

Parameters

$organization_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

listAttachmentsForSection()

List Attachments for a given Section.


    public
                    listAttachmentsForSection(string $section_id[, array<string|int, mixed>|null $query_params = [] ]) : object|bool


 $bf = new BrandfolderClient($api_key);

 $attachments_result = $bf->listAttachmentsForSection($section_id);
 if ($attachments_result) {
   foreach ($attachments_result->data as $attachment) {
     echo "Attachment: {$attachment->attributes->filename} ({$attachment->id}) <br/>";
   }
 }

Parameters

$section_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

listBrandfolders()

Gets Brandfolders to which the current user has access.


    public
                    listBrandfolders([array<string|int, mixed> $query_params = [] ]) : array<string|int, mixed>|object|false


$bf = new BrandfolderClient($api_key);
$brandfolders = $bf->listBrandfolders(['include' => 'collections']);

if ($brandfolders) {
  foreach ($brandfolders->data as $brandfolder) {
    echo "{$brandfolder->attributes->name} ({$brandfolder->id}) <br/>";
    if (!empty($brandfolder->collections)) {
      foreach ($brandfolder->collections as $collection_id => $collection) {
        echo "&nbsp; {$collection->name} ($collection_id) <br/>";
      }
    }
  }
}

Parameters

$query_params : array<string|int, mixed> = []

Return values

array<string|int, mixed>|object|false

listCollectionsForUser()

Lists Collections to which the current user has access.


    public
                    listCollectionsForUser([array<string|int, mixed>|null $query_params = [] ]) : object|false


$bf = new BrandfolderClient($api_key);

$result = $bf->listCollectionsForUser(['include' => 'brandfolder']);
if ($result) {
  $collections = $result->data;
  foreach ($collections as $collection) {
    echo "{$collection->attributes->name} ({$collection->id}) <br/>";
    if (!empty($collection->brandfolders)) {
      $brandfolder = reset($collection->brandfolders);
      echo "&nbsp; Brandfolder: {$brandfolder->name} ({$brandfolder->id}) <br/>";
    }
  }
}

Parameters

$query_params : array<string|int, mixed>|null = []

Return values

object|false

listCollectionsInBrandfolder()

List Collections belonging to a given Brandfolder.


    public
                    listCollectionsInBrandfolder([string|null $brandfolder_id = null ][, array<string|int, mixed>|null $query_params = [] ]) : array<string|int, mixed>|object|false


$bf = new BrandfolderClient($api_key);

$result = $bf->listCollectionsInBrandfolder($brandfolder_id, ['fields' => 'asset_count']);
if ($result) {
  $collections = $result->data;
  foreach ($collections as $collection) {
    echo "{$collection->attributes->name} ({$collection->id}): "
     . "{$collection->attributes->asset_count} assets <br/>";
  }
}

Parameters

$brandfolder_id : string|null = null
$query_params : array<string|int, mixed>|null = []

Return values

array<string|int, mixed>|object|false

listCustomFields()

Gets custom field data for a Brandfolder.


    public
                    listCustomFields([string|null $brandfolder_id = null ][, bool $include_values = false ][, bool $simple_format = false ]) : array<string|int, mixed>|object|false


$bf = new BrandfolderClient($api_key);

// Example A.
$result = $bf->listCustomFields($brandfolder_id);
if ($result) {
  foreach ($result->data as $custom_field) {
    echo "Custom field key name: {$custom_field->attributes->name} (ID: {$custom_field->id}) <br/>";
    echo "&nbsp; Allowed values: ";
    if ($custom_field->attributes->restricted) {
      echo implode(', ', $custom_field->attributes->allowed_values) . "<br/>";
    }
    else {
      echo "Any. <br/>";
    }
  }
}

// Example B.
$result = $bf->listCustomFields($brandfolder_id, TRUE);
if ($result) {
  foreach ($result->data as $custom_field) {
    $key_name = $custom_field->attributes->name;
    echo "Custom field key name: {$key_name} <br/>";
    $values_list = $custom_field->attributes->values;
    echo "&nbsp; All values currently in use: "
     . !empty($values_list) ? implode(', ', $values_list) : 'None' . "<br/>";
  }
}

// Example C.
$result = $bf->listCustomFields($brandfolder_id, TRUE, TRUE);
if ($result) {
  foreach ($result as $custom_field_name => $values) {
    echo "$custom_field_name: <br/>";
    foreach ($values as $value) {
      echo "&nbsp; $value <br/>";
    }
  }
}

Parameters

$brandfolder_id : string|null = null
$include_values : bool = false
$simple_format : bool = false: If true, return a simple array. The format of this array depends on the $include_values param. If true, return an array whose keys are custom field names and whose values are arrays of all the values that currently exist in Brandfolder for a given field. If false, return an array whose keys are custom field ids and whose values are custom field names.

Return values

array<string|int, mixed>|object|false

listCustomFieldValuesForAsset()

List custom field values for a given asset.


    public
                    listCustomFieldValuesForAsset(string $asset_id[, array<string|int, mixed>|null $query_params = [] ]) : object|false

Parameters

$asset_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|false

listInvitations()

Lists Invitations to an Organization, Brandfolder, Collection, Portal, or Brandguide.


    public
                    listInvitations(string $entity_type, string $entity_id[, array<string|int, mixed>|null $query_params = [] ]) : object|bool


$bf = new BrandfolderClient($api_key);

$invitations_result = $bf->listInvitations('brandfolder', 'brandfolder-id-abc-123');
if ($invitations_result) {
  foreach ($invitations_result->data as $invite) {
    echo "Invitation {$invite->id}: {$invite->attributes->email} "
     . "({$invite->attributes->permission_level}) <br/>";
  }
}

Parameters

$entity_type : string: The type of entity whose invites you are listing. Valid values are: organization, brandfolder, collection, portal, and brandguide.
$entity_id : string: The ID of the entity for which to list invitations.
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

listLabelsInBrandfolder()

List Labels defined in a given Brandfolder, structured as a nested associative array.


    public
                    listLabelsInBrandfolder([string|null $brandfolder_id = null ][, bool $simple_format = false ]) : array<string|int, mixed>|false


$bf = new BrandfolderClient($api_key);

// Example A. Get a multidimensional array representing the full set of
// Labels, with hierarchy preserved.
$labels = $bf->listLabelsInBrandfolder($brandfolder_id);
if ($labels) {
  // Iterate through the first two tiers of Labels.
  foreach ($labels as $label_id => $label_data) {
    $label = $label_data->label;
    echo "Label: {$label->attributes->name} ($label_id) <br />";
    if (!empty($label_data->children)) {
      foreach ($label_data->children as $child_id => $child_data) {
        $child = $child_data->label;
        echo "&nbsp; Nested Label: {$child->attributes->name} ($child_id) <br />";
        // There could be any number of tiers in the Label hierarchy.
        // To fully process the tree, you would need to use a recursive
        // function or comparable algorithm.
      }
    }
  }
}

// Example B. Get a flat array of Label names keyed by Label IDs.
$labels = $bf->listLabelsInBrandfolder($brandfolder_id, TRUE);
if ($labels) {
  foreach ($labels as $label_id => $label_name) {
    echo "Label: $label_name ($label_id) <br/>";
  }
}

Parameters

$brandfolder_id : string|null = null
$simple_format : bool = false: If true, return a flat array keyed by Label IDs and containing Label names. Otherwise, return a multidimensional array representing the full hierarchy of Labels, with all attributes for each Label item.

Return values

array<string|int, mixed>|false

listOrganizations()

Gets Brandfolder Organizations to which the current user belongs.


    public
                    listOrganizations([array<string|int, mixed> $query_params = [] ]) : object|false


$bf = new BrandfolderClient($api_key);

$organizations = $bf->listOrganizations(['include' => 'brandfolders']);
if ($organizations) {
  foreach ($organizations->data as $org) {
    echo "{$org->attributes->name} ({$org->attributes->id}) <br/>";
    if (!empty($org->brandfolders)) {
      foreach ($org->brandfolders as $brandfolder_id => $brandfolder) {
        echo "&nbsp; {$brandfolder->name} ($brandfolder_id) <br/>";
      }
    }
  }
}

Parameters

$query_params : array<string|int, mixed> = []

Return values

object|false

listSectionsInBrandfolder()

List Sections in a Brandfolder.


    public
                    listSectionsInBrandfolder([string|null $brandfolder_id = null ][, array<string|int, mixed> $query_params = [] ]) : object|false


$bf = new BrandfolderClient($api_key);

$result = $bf->listSectionsInBrandfolder($brandfolder_id, ['include' => 'brandfolder']);
if ($result) {
  $sections = $result->data;
  foreach ($sections as $section) {
    echo "{$section->attributes->name} ({$section->id}) <br/>";
    if (!empty($section->brandfolders)) {
      $brandfolder = reset($section->brandfolders);
      echo "&nbsp; Brandfolder: {$brandfolder->name} ({$brandfolder->id}) <br/>";
    }
  }
}

Parameters

$brandfolder_id : string|null = null
$query_params : array<string|int, mixed> = []

Return values

object|false

listTagsForAsset()

List tags for a given asset.


    public
                    listTagsForAsset(string $asset_id[, array<string|int, mixed>|null $query_params = [] ]) : object|bool


 $bf = new BrandfolderClient($api_key);

 $tags_result = $bf->listTagsForAsset($asset_id);
 if ($tags_result) {
   foreach ($tags_result->data as $tag) {
     echo "Tag: {$tag->attributes->name} ({$tag->id}) <br/>";
   }
 }

Parameters

$asset_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

listTagsInBrandfolder()

List Tags in a Brandfolder.


    public
                    listTagsInBrandfolder([string|null $brandfolder_id = null ][, array<string|int, mixed>|null $query_params = [] ]) : object|bool


 $bf = new BrandfolderClient($api_key);

 $tags_result = $bf->listTagsInBrandfolder($brandfolder_id);
 if ($tags_result) {
   foreach ($tags_result->data as $tag) {
     echo "Tag: {$tag->attributes->name} ({$tag->id}) <br/>";
   }
 }

Parameters

$brandfolder_id : string|null = null: The ID of the Brandfolder for which to list Tags. If not provided, the default Brandfolder ID will be used if set.
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

listTagsInCollection()

List tags in a Collection.


    public
                    listTagsInCollection([string|null $collection_id = null ][, array<string|int, mixed>|null $query_params = [] ]) : object|bool


 $bf = new BrandfolderClient($api_key);

 $tags_result = $bf->listTagsInCollection($collection_id);
 if ($tags_result) {
   foreach ($tags_result->data as $tag) {
     echo "Tag: {$tag->attributes->name} ({$tag->id}) <br/>";
   }
 }

Parameters

$collection_id : string|null = null: The ID of the Collection for which to list Tags. If not provided, the default Collection ID will be used if set.
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

listUserPermissionsForBrandfolder()

List user permissions for a Brandfolder.


    public
                    listUserPermissionsForBrandfolder(string $brandfolder_id[, array<string|int, mixed>|null $query_params = [] ]) : object|bool


$bf = new BrandfolderClient($api_key);

$permissions_result = $bf->listUserPermissionsForBrandfolder($brandfolder_id);
if ($permissions_result) {
  foreach ($permissions_result->data as $permission) {
    $user = reset($permission->users);
    echo "Permission {$permission->id}: {$user->first_name} {$user->last_name} ({$user->email}) "
     . "has permission level {$permission->attributes->permission_level} <br/>";
  }
}

Parameters

$brandfolder_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

listUserPermissionsForCollection()

List user permissions for a Collection.


    public
                    listUserPermissionsForCollection(string $collection_id[, array<string|int, mixed>|null $query_params = [] ]) : object|bool


$bf = new BrandfolderClient($api_key);

$permissions_result = $bf->listUserPermissionsForCollection($collection_id);
if ($permissions_result) {
 foreach ($permissions_result->data as $permission) {
   $user = reset($permission->users);
   echo "Permission {$permission->id}: {$user->first_name} {$user->last_name} ({$user->email}) "
     . "has permission level {$permission->attributes->permission_level} <br/>";
 }
}

Parameters

$collection_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

listUserPermissionsForOrganization()

List user permissions for an Organization.


    public
                    listUserPermissionsForOrganization(string $organization_id[, array<string|int, mixed>|null $query_params = [] ]) : object|bool


$bf = new BrandfolderClient($api_key);

$permissions_result = $bf->listUserPermissionsForOrganization($organization_id);
if ($permissions_result) {
 foreach ($permissions_result->data as $permission) {
   $user = reset($permission->users);
   echo "Permission {$permission->id}: {$user->first_name} {$user->last_name} ({$user->email}) "
     . "has permission level {$permission->attributes->permission_level} <br/>";
 }
}

Parameters

$organization_id : string
$query_params : array<string|int, mixed>|null = []

Return values

object|bool

moveLabel()

Move a Label to a new parent Label.


    public
                    moveLabel(string $label_id, string $new_parent_id) : object|false


$bf = new BrandfolderClient($api_key);
$result = $bf->moveLabel($label_id, $new_parent_id);

if ($result) {
  echo "Label $label_id moved successfully. <br/>";
}

Parameters

$label_id : string
$new_parent_id : string: The ID/key of the Label beneath which you want this Label to live. If you wish to move the Label to the top level, specify "root" here.

Return values

object|false

request()

Makes a request to the Brandfolder API, processes the result, and handles any errors that may arise.


    public
                    request(string $method, string $path[, array<string|int, mixed>|null $query_params = [] ][, array<string|int, mixed>|null $body = null ]) : object|false

Parameters

$method : string: The HTTP method to use for the request.
$path : string: The unique component of the API endpoint to use for this request.
$query_params : array<string|int, mixed>|null = []: Associative array of URL query parameters to add to the request.
$body : array<string|int, mixed>|null = null: Associative array of data to be sent as the body of the requests. This will be converted to JSON.

Return values

object|false —

An object representing JSON API response on success. This will typically consist of a data property containing the requested data, a meta property containing metadata about the response/context, and sometimes an included property containing additional data when available and when requested (via the include query param). false on failure.

setCustomFieldValuesForAssets()

Set custom field values for a given custom field, on one or more assets.


    public
                    setCustomFieldValuesForAssets(string $custom_field_key_id, array<string|int, mixed> $custom_field_values_per_asset) : bool|object

Parameters

$custom_field_key_id : string: The ID of the custom field key for which to set values.
$custom_field_values_per_asset : array<string|int, mixed>: An associative array where keys are asset IDs and values are the new values for the custom field on the asset.

Return values

bool|object

updateAsset()

Update an existing asset.


    public
                    updateAsset(string $asset_id[, string|null $name = null ][, string|null $description = null ][, array<string|int, mixed>|null $attachments = null ][, string|int|DateTime|null $availability_start = null ][, string|int|DateTime|null $availability_end = null ]) : object|false


 $bf = new BrandfolderClient($api_key);

 // Example A. Update an asset's name.
 $asset = $bf->updateAsset($asset_id, 'My Updated Asset Name');
 if ($asset) {
   echo "Asset $asset_id updated successfully. New name: {$asset->attributes->name} <br/>";
 }

 // Example B. Add a new attachment to an asset.
 $new_attachments = [
   [
     'url' => 'https://www.example.com/image-02.jpg',
   ],
 ];
 $asset = $bf->updateAsset($asset_id, NULL, NULL, $new_attachments);
 if ($asset) {
   echo "Attachment added to asset $asset_id. <br/>";
 }

 // Example C. Update an asset's expiration/unpublish date.
 $expiration_date = '2025-01-31';
 $asset = $bf->updateAsset($asset_id, NULL, NULL, NULL, NULL, $expiration_date);
 if ($asset) {
   echo "Asset $asset_id will now expire on $expiration_date. <br/>";
 }

Parameters

$asset_id : string
$name : string|null = null
$description : string|null = null
$attachments : array<string|int, mixed>|null = null: An array of Attachments to add to the asset. Each Attachment should be an associative array with keys url (required) and filename (optional). If the filename key is omitted, the filename will be extracted from the URL.
$availability_start : string|int|DateTime|null = null: To set/update the date at which this asset will be published, provide a date/time string, a timestamp, or a DateTime object. Alternatively, to remove/clear an existing start date, provide the string none.
$availability_end : string|int|DateTime|null = null: To set/update the date at which this asset will be unpublished, provide a date/time string, a timestamp, or a DateTime object. Alternatively, to remove/clear an existing end date, provide the string none.

Return values

object|false

updateAttachment()

Update an existing Attachment.


    public
                    updateAttachment(string $attachment_id[, string|null $url = null ][, string|null $filename = null ]) : object|false


$bf = new BrandfolderClient($api_key);
$result = $bf->updateAttachment($attachment_id, 'https://example.com/updated-image.jpg', 'updated-image.jpg');
if ($result) {
  echo "Attachment $attachment_id updated successfully. <br/>";
}

Parameters

$attachment_id : string
$url : string|null = null
$filename : string|null = null

Return values

object|false

updateCollection()

Update an existing Collection.


    public
                    updateCollection(string $collection_id, array<string|int, mixed> $attributes) : object|false


$bf = new BrandfolderClient($api_key);
$result = $bf->updateCollection($collection_id, ['tagline' => 'This is our most popular collection']);
if ($result) {
  echo "Collection $collection_id updated successfully. New tagline: {$result->data->attributes->tagline} <br/>";
}

Parameters

$collection_id : string
$attributes : array<string|int, mixed>: An associative array of attributes to update. Valid keys are name, tagline, and slug. Note: we recommend not to invent your own slug. If it is not valid (must be a string of letters, numbers, hyphens, and underscores), the request will fail with a 422 error. Default is to automatically assign a slug based on the name (a name of My Collection would make a slug of my-collection). If the provided slug is valid but not unique, it will have a number appended to make it unique.

Return values

object|false

updateCustomFieldKey()

Update an individual custom field key by ID.


    public
                    updateCustomFieldKey(string $custom_field_id, array<string|int, mixed> $attributes) : object|false


$bf = new BrandfolderClient($api_key);

$new_coffee_options = [
  'Costa Rican',
  'Peruvian',
  'Colombian',
  'Ethiopian',
  'Sumatran',
  'Global Blend'
];

$result = $bf->updateCustomFieldKey($custom_field_id, ['allowed_values' => $new_coffee_options]);

Parameters

$custom_field_id : string
$attributes : array<string|int, mixed>: An associative array of attributes to update. Valid keys are name and allowed_values.

Return values

object|false

updateCustomFieldValue()

Update an existing custom field value by value ID


    public
                    updateCustomFieldValue(string $custom_field_value_id, string $value) : object|false

Note: the custom field value ID is different than the custom field key ID. Every single value instance has its own ID.

Parameters

$custom_field_value_id : string
$value : string

Return values

object|false

updateLabel()

Update an existing Label.


    public
                    updateLabel(string $label_id, array<string|int, mixed> $new_name) : object|false


$bf = new BrandfolderClient($api_key);
$result = $bf->updateLabel($label_id, 'My New Label Name');
if ($result) {
  echo "Label renamed successfully. <br/>";
}

Parameters

$label_id : string
$new_name : array<string|int, mixed>: A new name for the Label. Note: parent_id/parent_key is not an option here. If you wish to relocate the Label, use the moveLabel() method.

Return values

object|false

updateTag()

Update an existing tag. Note: this only updates one particular instance of a tag name. Whenever you create a new tag for an asset, a new ID is created for that instance, even if the tag name is already used elsewhere.


    public
                    updateTag(string $tag_id, string $tag_name) : object|bool

Therefore, a given tag ID is only ever used in one place.


 $bf = new BrandfolderClient($api_key);

 $tag_id = 'tag-id-abc-123';
 $tag_name = 'Renamed Tag';
 $result = $bf->updateTag($tag_id, $tag_name);
 if ($result) {
   echo "Tag $tag_id successfully renamed to $tag_name.";
 }

Parameters

$tag_id : string
$tag_name : string

Return values

object|bool

verboseLoggingIsEnabled()

Determine whether verbose logging is enabled.


    public
                    verboseLoggingIsEnabled() : bool

Return values

bool

decorateAsset()

Modify an asset object to contain useful values for each included attribute rather than just a list of items with IDs, and to clean up custom field and attachment data.


    protected
                    decorateAsset(object &$asset, array<string|int, mixed> $included_data) : void

Parameters

$asset : object: The item with relationships to be processed. This will typically be a member of the data array returned from an API request, and could correspond to an asset, attachment, Brandfolder, etc.
$included_data : array<string|int, mixed>: The included array returned from an API request for which you provided the include query param.

Note: This is retained mainly for backwards compatibility. It could be expanded to include more asset-specific functionality, but all such functionality is currently contained within processRelationships().

decorateAttachment()

Update an attachment to contain useful values for each included attribute rather than just a list of items with IDs.


    protected
                    decorateAttachment(object &$attachment, array<string|int, mixed> $included_data) : void

Parameters

$attachment : object: The item with relationships to be processed. This will typically be a member of the data array returned from an API request, and could correspond to an asset, attachment, Brandfolder, etc.
$included_data : array<string|int, mixed>: The included array returned from an API request for which you provided the include query param.

Note: This is retained mainly for backwards compatibility. It could be expanded to include more attachment-specific functionality.

formatDateTime()

Accept various types of date/time inputs and produce a date/time string in a format suitable for the Brandfolder API.


    protected
                    formatDateTime(string|int|DateTime $date_time) : string

Parameters

$date_time : string|int|DateTime: An English date/time string, timestamp, or DateTime object.

Return values

string

jsonDecode()

Compatibility wrapper to support various json-decode methods.


    protected
                    jsonDecode(mixed $data) : mixed

Parameters

$data : mixed

jsonEncode()

Compatibility wrapper to support various json-encode methods.


    protected
                    jsonEncode(mixed $data) : false|string

Parameters

$data : mixed

Return values

false|string

log()

Add log data.


    protected
                    log(string $entry) : void

Parameters

$entry : string

processRelationships()

Restructure an entity to contain useful values for each included attribute rather than just a list of items with IDs that need to be cross-referenced with the "included" data array returned by the API.


    protected
                    processRelationships(object &$entity, array<string|int, mixed> $included_data) : void

Also restructure custom field and attachment data (these will often be present if $entity corresponds to an asset).

Parameters

$entity : object: The item with relationships to be processed. This will typically be a member of the "data" array returned from an API request, and could correspond to an asset, attachment, Brandfolder, etc.
$included_data : array<string|int, mixed>: The "included" array returned from an API request for which you provided the "include" query param.

processResultData()

Improve the usefulness of data returned from GET requests.


    protected
                    processResultData(object &$result) : void

Parameters

$result : object

restructureIncludedData()

Structure included data as an associative array of items grouped by type and indexed therein by ID.


    protected
                    restructureIncludedData(object &$result) : void

Parameters

$result : object

BrandfolderClient in package Brandfolder

Table of Contents

Properties

Methods

Properties

$default_brandfolder_id

Tags

$default_collection_id

Tags

$default_items_per_page

$message

$status

$api_key

$endpoint

$http_client

$log_data

$verbose_logging_mode

Methods

__construct()

Parameters

addAssetsToLabel()

Parameters

Tags

Return values

addCustomFieldsToAsset()

Parameters

Tags

Return values

clearLogData()

createAsset()

Parameters

Tags

Return values

createAssets()

Parameters

Tags

Return values

createBrandfolderInOrganization()

Parameters

Tags

Return values

createCollectionInBrandfolder()

Parameters

Tags

Return values

createCustomFieldKeysForBrandfolder()

Parameters

Tags

Return values

createInvitation()

Parameters

Tags

Return values

createLabelInBrandfolder()

Parameters

Tags

Return values

createSectionInBrandfolder()

Parameters

Tags

Return values

createTagsForAsset()

Parameters

Tags

Return values

deleteAsset()

Parameters

Tags

Return values

deleteAttachment()

Parameters

Tags

Return values

deleteCollection()

Parameters

Tags

Return values

deleteCustomFieldKey()

Parameters

Tags

BrandfolderClient
in package

Brandfolder