mirror of
https://github.com/LukeHagar/plexphp.git
synced 2025-12-10 12:37:46 +00:00
626 lines
23 KiB
Markdown
626 lines
23 KiB
Markdown
# Library
|
|
|
|
|
|
## Overview
|
|
|
|
API Calls interacting with Plex Media Server Libraries
|
|
|
|
|
|
### Available Operations
|
|
|
|
* [getFileHash](#getfilehash) - Get Hash Value
|
|
* [getRecentlyAdded](#getrecentlyadded) - Get Recently Added
|
|
* [getLibraries](#getlibraries) - Get All Libraries
|
|
* [getLibrary](#getlibrary) - Get Library Details
|
|
* [deleteLibrary](#deletelibrary) - Delete Library Section
|
|
* [getLibraryItems](#getlibraryitems) - Get Library Items
|
|
* [refreshLibrary](#refreshlibrary) - Refresh Library
|
|
* [searchLibrary](#searchlibrary) - Search Library
|
|
* [getMetadata](#getmetadata) - Get Items Metadata
|
|
* [getMetadataChildren](#getmetadatachildren) - Get Items Children
|
|
* [getOnDeck](#getondeck) - Get On Deck
|
|
|
|
## getFileHash
|
|
|
|
This resource returns hash values for local files
|
|
|
|
### Example Usage
|
|
|
|
```php
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
require 'vendor/autoload.php';
|
|
|
|
use \LukeHagar\Plex_API;
|
|
use \LukeHagar\Plex_API\Models\Components;
|
|
use \LukeHagar\Plex_API\Models\Operations;
|
|
|
|
$security = new Components\Security();
|
|
$security->accessToken = '<YOUR_API_KEY_HERE>';
|
|
|
|
$sdk = Plex_API\PlexAPI::builder()
|
|
->setXPlexClientIdentifier('Postman')
|
|
->setSecurity($security)->build();
|
|
|
|
try {
|
|
|
|
|
|
$response = $sdk->library->getFileHash('file://C:\Image.png&type=13', 4462.17);
|
|
|
|
if ($response->statusCode === 200) {
|
|
// handle response
|
|
}
|
|
} catch (Throwable $e) {
|
|
// handle exception
|
|
}
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description | Example |
|
|
| ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- |
|
|
| `url` | *string* | :heavy_check_mark: | This is the path to the local file, must be prefixed by `file://` | file://C:\Image.png&type=13 |
|
|
| `type` | *float* | :heavy_minus_sign: | Item type | |
|
|
|
|
|
|
### Response
|
|
|
|
**[?\LukeHagar\Plex_API\Models\Operations\GetFileHashResponse](../../Models/Operations/GetFileHashResponse.md)**
|
|
|
|
|
|
## getRecentlyAdded
|
|
|
|
This endpoint will return the recently added content.
|
|
|
|
|
|
### Example Usage
|
|
|
|
```php
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
require 'vendor/autoload.php';
|
|
|
|
use \LukeHagar\Plex_API;
|
|
use \LukeHagar\Plex_API\Models\Components;
|
|
|
|
$security = new Components\Security();
|
|
$security->accessToken = '<YOUR_API_KEY_HERE>';
|
|
|
|
$sdk = Plex_API\PlexAPI::builder()
|
|
->setXPlexClientIdentifier('Postman')
|
|
->setSecurity($security)->build();
|
|
|
|
try {
|
|
$response = $sdk->library->getRecentlyAdded();
|
|
|
|
if ($response->twoHundredApplicationJsonObject !== null) {
|
|
// handle response
|
|
}
|
|
} catch (Throwable $e) {
|
|
// handle exception
|
|
}
|
|
```
|
|
|
|
|
|
### Response
|
|
|
|
**[?\LukeHagar\Plex_API\Models\Operations\GetRecentlyAddedResponse](../../Models/Operations/GetRecentlyAddedResponse.md)**
|
|
|
|
|
|
## getLibraries
|
|
|
|
A library section (commonly referred to as just a library) is a collection of media.
|
|
Libraries are typed, and depending on their type provide either a flat or a hierarchical view of the media.
|
|
For example, a music library has an artist > albums > tracks structure, whereas a movie library is flat.
|
|
|
|
Libraries have features beyond just being a collection of media; for starters, they include information about supported types, filters and sorts.
|
|
This allows a client to provide a rich interface around the media (e.g. allow sorting movies by release year).
|
|
|
|
|
|
### Example Usage
|
|
|
|
```php
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
require 'vendor/autoload.php';
|
|
|
|
use \LukeHagar\Plex_API;
|
|
use \LukeHagar\Plex_API\Models\Components;
|
|
|
|
$security = new Components\Security();
|
|
$security->accessToken = '<YOUR_API_KEY_HERE>';
|
|
|
|
$sdk = Plex_API\PlexAPI::builder()
|
|
->setXPlexClientIdentifier('Postman')
|
|
->setSecurity($security)->build();
|
|
|
|
try {
|
|
$response = $sdk->library->getLibraries();
|
|
|
|
if ($response->twoHundredApplicationJsonObject !== null) {
|
|
// handle response
|
|
}
|
|
} catch (Throwable $e) {
|
|
// handle exception
|
|
}
|
|
```
|
|
|
|
|
|
### Response
|
|
|
|
**[?\LukeHagar\Plex_API\Models\Operations\GetLibrariesResponse](../../Models/Operations/GetLibrariesResponse.md)**
|
|
|
|
|
|
## getLibrary
|
|
|
|
## Library Details Endpoint
|
|
|
|
This endpoint provides comprehensive details about the library, focusing on organizational aspects rather than the content itself.
|
|
|
|
The details include:
|
|
|
|
### Directories
|
|
Organized into three categories:
|
|
|
|
- **Primary Directories**:
|
|
- Used in some clients for quick access to media subsets (e.g., "All", "On Deck").
|
|
- Most can be replicated via media queries.
|
|
- Customizable by users.
|
|
|
|
- **Secondary Directories**:
|
|
- Marked with `secondary="1"`.
|
|
- Used in older clients for structured navigation.
|
|
|
|
- **Special Directories**:
|
|
- Includes a "By Folder" entry for filesystem-based browsing.
|
|
- Contains an obsolete `search="1"` entry for on-the-fly search dialog creation.
|
|
|
|
### Types
|
|
Each type in the library comes with a set of filters and sorts, aiding in building dynamic media controls:
|
|
|
|
- **Type Object Attributes**:
|
|
- `key`: Endpoint for the media list of this type.
|
|
- `type`: Metadata type (if standard Plex type).
|
|
- `title`: Title for this content type (e.g., "Movies").
|
|
|
|
- **Filter Objects**:
|
|
- Subset of the media query language.
|
|
- Attributes include `filter` (name), `filterType` (data type), `key` (endpoint for value range), and `title`.
|
|
|
|
- **Sort Objects**:
|
|
- Description of sort fields.
|
|
- Attributes include `defaultDirection` (asc/desc), `descKey` and `key` (sort parameters), and `title`.
|
|
|
|
> **Note**: Filters and sorts are optional; without them, no filtering controls are rendered.
|
|
|
|
|
|
### Example Usage
|
|
|
|
```php
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
require 'vendor/autoload.php';
|
|
|
|
use \LukeHagar\Plex_API;
|
|
use \LukeHagar\Plex_API\Models\Components;
|
|
use \LukeHagar\Plex_API\Models\Operations;
|
|
|
|
$security = new Components\Security();
|
|
$security->accessToken = '<YOUR_API_KEY_HERE>';
|
|
|
|
$sdk = Plex_API\PlexAPI::builder()
|
|
->setXPlexClientIdentifier('Postman')
|
|
->setSecurity($security)->build();
|
|
|
|
try {
|
|
|
|
|
|
$response = $sdk->library->getLibrary(1000, Operations\IncludeDetails::Zero);
|
|
|
|
if ($response->twoHundredApplicationJsonObject !== null) {
|
|
// handle response
|
|
}
|
|
} catch (Throwable $e) {
|
|
// handle exception
|
|
}
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description | Example |
|
|
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| `sectionId` | *float* | :heavy_check_mark: | the Id of the library to query | 1000 |
|
|
| `includeDetails` | [\LukeHagar\Plex_API\Models\Operations\IncludeDetails](../../Models/Operations/IncludeDetails.md) | :heavy_minus_sign: | Whether or not to include details for a section (types, filters, and sorts). <br/>Only exists for backwards compatibility, media providers other than the server libraries have it on always.<br/> | |
|
|
|
|
|
|
### Response
|
|
|
|
**[?\LukeHagar\Plex_API\Models\Operations\GetLibraryResponse](../../Models/Operations/GetLibraryResponse.md)**
|
|
|
|
|
|
## deleteLibrary
|
|
|
|
Delate a library using a specific section
|
|
|
|
### Example Usage
|
|
|
|
```php
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
require 'vendor/autoload.php';
|
|
|
|
use \LukeHagar\Plex_API;
|
|
use \LukeHagar\Plex_API\Models\Components;
|
|
use \LukeHagar\Plex_API\Models\Operations;
|
|
|
|
$security = new Components\Security();
|
|
$security->accessToken = '<YOUR_API_KEY_HERE>';
|
|
|
|
$sdk = Plex_API\PlexAPI::builder()
|
|
->setXPlexClientIdentifier('Postman')
|
|
->setSecurity($security)->build();
|
|
|
|
try {
|
|
|
|
|
|
$response = $sdk->library->deleteLibrary(1000);
|
|
|
|
if ($response->statusCode === 200) {
|
|
// handle response
|
|
}
|
|
} catch (Throwable $e) {
|
|
// handle exception
|
|
}
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description | Example |
|
|
| ------------------------------ | ------------------------------ | ------------------------------ | ------------------------------ | ------------------------------ |
|
|
| `sectionId` | *float* | :heavy_check_mark: | the Id of the library to query | 1000 |
|
|
|
|
|
|
### Response
|
|
|
|
**[?\LukeHagar\Plex_API\Models\Operations\DeleteLibraryResponse](../../Models/Operations/DeleteLibraryResponse.md)**
|
|
|
|
|
|
## getLibraryItems
|
|
|
|
Fetches details from a specific section of the library identified by a section key and a tag. The tag parameter accepts the following values:
|
|
- `all`: All items in the section.
|
|
- `unwatched`: Items that have not been played.
|
|
- `newest`: Items that are recently released.
|
|
- `recentlyAdded`: Items that are recently added to the library.
|
|
- `recentlyViewed`: Items that were recently viewed.
|
|
- `onDeck`: Items to continue watching.
|
|
- `collection`: Items categorized by collection.
|
|
- `edition`: Items categorized by edition.
|
|
- `genre`: Items categorized by genre.
|
|
- `year`: Items categorized by year of release.
|
|
- `decade`: Items categorized by decade.
|
|
- `director`: Items categorized by director.
|
|
- `actor`: Items categorized by starring actor.
|
|
- `country`: Items categorized by country of origin.
|
|
- `contentRating`: Items categorized by content rating.
|
|
- `rating`: Items categorized by rating.
|
|
- `resolution`: Items categorized by resolution.
|
|
- `firstCharacter`: Items categorized by the first letter.
|
|
- `folder`: Items categorized by folder.
|
|
|
|
|
|
### Example Usage
|
|
|
|
```php
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
require 'vendor/autoload.php';
|
|
|
|
use \LukeHagar\Plex_API;
|
|
use \LukeHagar\Plex_API\Models\Components;
|
|
use \LukeHagar\Plex_API\Models\Operations;
|
|
|
|
$security = new Components\Security();
|
|
$security->accessToken = '<YOUR_API_KEY_HERE>';
|
|
|
|
$sdk = Plex_API\PlexAPI::builder()
|
|
->setXPlexClientIdentifier('Postman')
|
|
->setSecurity($security)->build();
|
|
|
|
try {
|
|
|
|
|
|
$response = $sdk->library->getLibraryItems(1, Operations\Tag::Genre);
|
|
|
|
if ($response->twoHundredApplicationJsonObject !== null) {
|
|
// handle response
|
|
}
|
|
} catch (Throwable $e) {
|
|
// handle exception
|
|
}
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description | Example |
|
|
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
|
| `sectionId` | *int* | :heavy_check_mark: | the Id of the library to query | 1 |
|
|
| `tag` | [\LukeHagar\Plex_API\Models\Operations\Tag](../../Models/Operations/Tag.md) | :heavy_check_mark: | A key representing a specific tag within the section. | |
|
|
|
|
|
|
### Response
|
|
|
|
**[?\LukeHagar\Plex_API\Models\Operations\GetLibraryItemsResponse](../../Models/Operations/GetLibraryItemsResponse.md)**
|
|
|
|
|
|
## refreshLibrary
|
|
|
|
This endpoint Refreshes the library.
|
|
|
|
|
|
### Example Usage
|
|
|
|
```php
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
require 'vendor/autoload.php';
|
|
|
|
use \LukeHagar\Plex_API;
|
|
use \LukeHagar\Plex_API\Models\Components;
|
|
use \LukeHagar\Plex_API\Models\Operations;
|
|
|
|
$security = new Components\Security();
|
|
$security->accessToken = '<YOUR_API_KEY_HERE>';
|
|
|
|
$sdk = Plex_API\PlexAPI::builder()
|
|
->setXPlexClientIdentifier('Postman')
|
|
->setSecurity($security)->build();
|
|
|
|
try {
|
|
|
|
|
|
$response = $sdk->library->refreshLibrary(934.16);
|
|
|
|
if ($response->statusCode === 200) {
|
|
// handle response
|
|
}
|
|
} catch (Throwable $e) {
|
|
// handle exception
|
|
}
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| -------------------------------- | -------------------------------- | -------------------------------- | -------------------------------- |
|
|
| `sectionId` | *float* | :heavy_check_mark: | the Id of the library to refresh |
|
|
|
|
|
|
### Response
|
|
|
|
**[?\LukeHagar\Plex_API\Models\Operations\RefreshLibraryResponse](../../Models/Operations/RefreshLibraryResponse.md)**
|
|
|
|
|
|
## searchLibrary
|
|
|
|
Search for content within a specific section of the library.
|
|
|
|
### Types
|
|
Each type in the library comes with a set of filters and sorts, aiding in building dynamic media controls:
|
|
|
|
- **Type Object Attributes**:
|
|
- `type`: Metadata type (if standard Plex type).
|
|
- `title`: Title for this content type (e.g., "Movies").
|
|
|
|
- **Filter Objects**:
|
|
- Subset of the media query language.
|
|
- Attributes include `filter` (name), `filterType` (data type), `key` (endpoint for value range), and `title`.
|
|
|
|
- **Sort Objects**:
|
|
- Description of sort fields.
|
|
- Attributes include `defaultDirection` (asc/desc), `descKey` and `key` (sort parameters), and `title`.
|
|
|
|
> **Note**: Filters and sorts are optional; without them, no filtering controls are rendered.
|
|
|
|
|
|
### Example Usage
|
|
|
|
```php
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
require 'vendor/autoload.php';
|
|
|
|
use \LukeHagar\Plex_API;
|
|
use \LukeHagar\Plex_API\Models\Components;
|
|
use \LukeHagar\Plex_API\Models\Operations;
|
|
|
|
$security = new Components\Security();
|
|
$security->accessToken = '<YOUR_API_KEY_HERE>';
|
|
|
|
$sdk = Plex_API\PlexAPI::builder()
|
|
->setXPlexClientIdentifier('Postman')
|
|
->setSecurity($security)->build();
|
|
|
|
try {
|
|
|
|
|
|
$response = $sdk->library->searchLibrary(933505, Operations\Type::Four);
|
|
|
|
if ($response->twoHundredApplicationJsonObject !== null) {
|
|
// handle response
|
|
}
|
|
} catch (Throwable $e) {
|
|
// handle exception
|
|
}
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
|
| `sectionId` | *int* | :heavy_check_mark: | the Id of the library to query |
|
|
| `type` | [\LukeHagar\Plex_API\Models\Operations\Type](../../Models/Operations/Type.md) | :heavy_check_mark: | Plex content type to search for |
|
|
|
|
|
|
### Response
|
|
|
|
**[?\LukeHagar\Plex_API\Models\Operations\SearchLibraryResponse](../../Models/Operations/SearchLibraryResponse.md)**
|
|
|
|
|
|
## getMetadata
|
|
|
|
This endpoint will return the metadata of a library item specified with the ratingKey.
|
|
|
|
|
|
### Example Usage
|
|
|
|
```php
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
require 'vendor/autoload.php';
|
|
|
|
use \LukeHagar\Plex_API;
|
|
use \LukeHagar\Plex_API\Models\Components;
|
|
use \LukeHagar\Plex_API\Models\Operations;
|
|
|
|
$security = new Components\Security();
|
|
$security->accessToken = '<YOUR_API_KEY_HERE>';
|
|
|
|
$sdk = Plex_API\PlexAPI::builder()
|
|
->setXPlexClientIdentifier('Postman')
|
|
->setSecurity($security)->build();
|
|
|
|
try {
|
|
|
|
|
|
$response = $sdk->library->getMetadata(8382.31);
|
|
|
|
if ($response->twoHundredApplicationJsonObject !== null) {
|
|
// handle response
|
|
}
|
|
} catch (Throwable $e) {
|
|
// handle exception
|
|
}
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| ----------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------- |
|
|
| `ratingKey` | *float* | :heavy_check_mark: | the id of the library item to return the children of. |
|
|
|
|
|
|
### Response
|
|
|
|
**[?\LukeHagar\Plex_API\Models\Operations\GetMetadataResponse](../../Models/Operations/GetMetadataResponse.md)**
|
|
|
|
|
|
## getMetadataChildren
|
|
|
|
This endpoint will return the children of of a library item specified with the ratingKey.
|
|
|
|
|
|
### Example Usage
|
|
|
|
```php
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
require 'vendor/autoload.php';
|
|
|
|
use \LukeHagar\Plex_API;
|
|
use \LukeHagar\Plex_API\Models\Components;
|
|
use \LukeHagar\Plex_API\Models\Operations;
|
|
|
|
$security = new Components\Security();
|
|
$security->accessToken = '<YOUR_API_KEY_HERE>';
|
|
|
|
$sdk = Plex_API\PlexAPI::builder()
|
|
->setXPlexClientIdentifier('Postman')
|
|
->setSecurity($security)->build();
|
|
|
|
try {
|
|
|
|
|
|
$response = $sdk->library->getMetadataChildren(1539.14);
|
|
|
|
if ($response->twoHundredApplicationJsonObject !== null) {
|
|
// handle response
|
|
}
|
|
} catch (Throwable $e) {
|
|
// handle exception
|
|
}
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| ----------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------- |
|
|
| `ratingKey` | *float* | :heavy_check_mark: | the id of the library item to return the children of. |
|
|
|
|
|
|
### Response
|
|
|
|
**[?\LukeHagar\Plex_API\Models\Operations\GetMetadataChildrenResponse](../../Models/Operations/GetMetadataChildrenResponse.md)**
|
|
|
|
|
|
## getOnDeck
|
|
|
|
This endpoint will return the on deck content.
|
|
|
|
|
|
### Example Usage
|
|
|
|
```php
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
require 'vendor/autoload.php';
|
|
|
|
use \LukeHagar\Plex_API;
|
|
use \LukeHagar\Plex_API\Models\Components;
|
|
|
|
$security = new Components\Security();
|
|
$security->accessToken = '<YOUR_API_KEY_HERE>';
|
|
|
|
$sdk = Plex_API\PlexAPI::builder()
|
|
->setXPlexClientIdentifier('Postman')
|
|
->setSecurity($security)->build();
|
|
|
|
try {
|
|
$response = $sdk->library->getOnDeck();
|
|
|
|
if ($response->twoHundredApplicationJsonObject !== null) {
|
|
// handle response
|
|
}
|
|
} catch (Throwable $e) {
|
|
// handle exception
|
|
}
|
|
```
|
|
|
|
|
|
### Response
|
|
|
|
**[?\LukeHagar\Plex_API\Models\Operations\GetOnDeckResponse](../../Models/Operations/GetOnDeckResponse.md)**
|
|
|