### Install Laravel Printing via Composer

Source: https://github.com/rawilk/laravel-printing/blob/main/README.md

Install the package using Composer. This command adds the package to your project's dependencies.

```bash
composer require rawilk/laravel-printing
```

--------------------------------

### Configure CUPS Server Credentials

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/overview.md

Enter your CUPS installation credentials into the .env file. The IP address can also be a hostname.

```bash
CUPS_SERVER_IP=your-ip-address
CUPS_SERVER_USERNAME=your-username
CUPS_SERVER_PASSWORD=your-password
CUPS_SERVER_PORT=631 # This is the typical value
CUPS_SERVER_SECURE=false # true if using https
```

--------------------------------

### Configure PrintNode API Key in .env

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/overview.md

Set your PrintNode API key in the .env file for package configuration. This is the simplest method for most setups.

```bash
PRINT_NODE_API_KEY=your-api-key
```

--------------------------------

### Alternate CUPS Runtime Configuration

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/overview.md

Configure CUPS at runtime, which is useful in multi-tenant setups. Ensure null values are used in .env for global configuration in these scenarios.

```php
use Rawilk\Printing\Api\Cups\Cups;

Cups::setIp('your-ip');
Cups::setAuth('your-username', 'your-password');
Cups::setPort(631);
Cups::setSecure(true);
```

--------------------------------

### ReceiptPrinter Usage

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/advanced-usage/receipts.md

Example of generating a receipt string with various formatting options and then sending it for printing.

```APIDOC
## ReceiptPrinter Usage

### Description
This example demonstrates how to instantiate the `ReceiptPrinter`, apply formatting like centering and two-column text, add a barcode, and finally cut the paper. It also shows how to send the generated receipt content to a printer task.

### Code Example
```php
use Rawilk\Printing\Receipts\ReceiptPrinter;

// First generate the receipt
$receipt = (string) (new ReceiptPrinter)
    ->centerAlign()
    ->text('My heading')
    ->leftAlign()
    ->line()
    ->twoColumnText('Item 1', '2.00')
    ->twoColumnText('Item 2', '4.00')
    ->feed(2)
    ->centerAlign()
    ->barcode('1234')
    ->cut();

// Now send the string to your receipt printer
// Assuming Printing facade is available and configured
// Printing::newPrintTask()
//     ->printer($receiptPrinterId)
//     ->content($receipt)
//     ->send();
```

### Notes
- The `ReceiptPrinter` generates a string that can be sent to a printer.
- If using the PrintNode driver, content is automatically base64 encoded.
- The `Printing::newPrintTask()` method is used to send the content, assuming the `Printing` facade is set up.
```

--------------------------------

### Fetch All Printers

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/printer-service.md

Retrieve all printers installed on the CUPS server. This method is part of the CupsClient's printers API.

```php
$printers = $client->printers->all();
```

--------------------------------

### Create a New Print Job

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/printjob-service.md

Creates a new print job to be sent to a physical printer via PrintNode. It's recommended to use a `PendingPrintJob` object for parameters. This example demonstrates setting content, content type, printer, title, and source.

```php
use Rawilk\Printing\Api\PrintNode\PendingPrintJob;
use Rawilk\Printing\Api\PrintNode\Enums\ContentType;

$pendingJob = PendingPrintJob::make()
    ->setContent('hello world')
    ->setContentType(ContentType::RawBase64)
    ->setPrinter($printerId)
    ->setTitle('My job title')
    ->setSource(config('app.name'));

$printJob = $client->printJobs->create($pendingJob);
```

--------------------------------

### Retrieve All Printers

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/printer-service.md

Fetches a collection of all printers installed on the CUPS server. This method can accept optional parameters for filtering or options.

```APIDOC
## all

### Description
Retrieve all printers associated installed on the CUPS server.

### Method Signature
`all(array|null $params = null, null|array|RequestOptions $opts = null): Collection<int, Rawilk\Printing\Api\Cups\Resources\Printer>

### Parameters
#### `$params`
- type: `array|null`
- default: `null`
- description: Optional parameters for filtering or options.

#### `$opts`
- type: `null|array|RequestOptions`
- default: `null`
- description: Request options.

### Example Usage
```php
$printers = $client->printers->all();
```
```

--------------------------------

### Initializing the PrintNode Client

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/api.md

Demonstrates how to resolve and initialize the PrintNode client from the application container, optionally providing an API key.

```APIDOC
## Initializing the PrintNode Client

### Description
Resolve the PrintNode client from the container. An API key can be provided during instantiation or set later.

### Method
```php
app(Rawilk\Printing\Api\PrintNode\PrintNodeClient::class, ['config' => ['api_key' => 'my-key']])
```

### Parameters
* `config` (array) - Optional. An array of configuration options, including 'api_key'.
  * `api_key` (string) - The API key for authentication. Optional, can be set later.
```

--------------------------------

### Instantiate CUPS Client

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/api.md

Resolve the CupsClient from the container and provide configuration options. Providing credentials here is optional but recommended if not set elsewhere.

```php
use Rawilk\Printing\Api\Cups\CupsClient;

$client = app(CupsClient::class, [
    'config' => [
        'ip' => 'your-ip',
        'username' => 'your-username',
        'password' => 'your-password',
        'port' => 631,
        'secure' => true,
    ],
]);
```

--------------------------------

### Get Print Job States

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/printjob-service.md

Retrieves all the reported states for a specific print job.

```APIDOC
## GET /printjobs/{id}/states

### Description
Get all the states that PrintNode has reported for the print job.

### Method
GET

### Endpoint
/printjobs/{id}/states

### Parameters
#### Path Parameters
- **id** (int) - Required - The unique identifier of the print job.

#### Query Parameters
- **params** (array|null) - Optional - Parameters for filtering or sorting.
- **opts** (null|array|RequestOptions) - Optional - Additional options for the request.

### Response
#### Success Response (200)
- **states** (Collection<int, Rawilk\Printing\Api\PrintNode\Resources\PrintJobState>) - A collection of print job state objects.

#### Response Example
```json
[
  {
    "state": "pending",
    "timestamp": "2023-10-26T15:30:00+00:00"
  },
  {
    "state": "printing",
    "timestamp": "2023-10-26T15:31:00+00:00"
  }
]
```
```

--------------------------------

### Create a Print Job with Request Options

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/api.md

Create a print job by providing job details and server credentials via the 'opts' argument. This allows for per-request credential overrides.

```php
$client->printJobs->create([...], opts: [
    'ip' => 'your-ip',
    'username' => 'your-username',
    'password' => 'your-password',
    'port' => 631,
    'secure' => true,
]);
```

--------------------------------

### Conditionally Apply Print Task Options

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/basic-usage/print-tasks.md

Use the 'when' method to conditionally apply configurations like setting content based on a condition. This requires the 'Conditionable' trait.

```php
use Rawilk\Printing\PrintTask;

Printing::newPrintTask()
    ->when(
        $someCondition === true,
        fn (PrintTask $task) => $task->content('...')
    )
```

--------------------------------

### Initialize PrintNode API Client

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/api.md

Resolve the PrintNode client from the container. Providing an API key to the constructor is optional, but it must be set manually on the client before making a request.

```php
use Rawilk\Printing\Api\PrintNode\PrintNodeClient;

$client = app(PrintNodeClient::class, [
    'config' => ['api_key' => 'my-key'],
]);
```

--------------------------------

### Switching Print Drivers at Runtime

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/advanced-usage/multiple-drivers.md

Use the `driver()` method to specify which driver to use for subsequent print tasks. This is useful when you need to send one job to a service like PrintNode and another to a local CUPS server.

```php
use Rawilk\Printing\Enums\PrintDriver;

// Send a job to printnode
Printing::newPrintTask()
    ->printer($printerId)
    ->file('file_path.pdf')
    ->send();

// Send a job to the cups server
Printing::driver(PrintDriver::Cups)
    ->newPrintTask()
    ->printer($cupsPrinterId)
    ->file('file_path.pdf')
    ->send();
```

--------------------------------

### Access the Default Printer

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/basic-usage/basic-usage.md

Get the default printer instance or its ID as configured in the application's config file. This method only works for the default driver.

```php
// returns an instance of Rawilk\Printing\Contracts\Printer if the printer is found
Printing::defaultPrinter();

// or for just the id
Printing::defaultPrinterId();
```

--------------------------------

### Using Services

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/api.md

Illustrates how to use the different service classes provided by the CUPS client to interact with specific resources.

```APIDOC
## Services

### Description
The CUPS implementation for this package splits requests to the server into service classes, depending on the resource you're creating or retrieving.

### Example: Retrieving All Printers
For example, to retrieve all printers, you would use the `printers` service class on the client.

```php
$client->printers->all();
```

More information about each service can be found on that service's doc page.
```

--------------------------------

### Retrieve Print Jobs for a Printer

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/printer-service.md

Retrieves all print jobs associated with a specific printer ID. To get print jobs for multiple printers, pass an array of printer IDs.

```php
$printJobs = $client->printers->printJobs(123);
```

--------------------------------

### Using Services

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/api.md

Illustrates how to access different API services (e.g., printers, print jobs) through the client to perform specific operations.

```APIDOC
## Using Services

### Description
API calls are organized into service classes based on the resource type. Access these services via the client instance.

### Example
To retrieve all printers:
```php
$client->printers->all();
```

### Note
More details on specific service methods can be found on their respective documentation pages.
```

--------------------------------

### Resolving the CupsClient

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/api.md

Demonstrates how to resolve and instantiate the CupsClient from the service container, including initial configuration.

```APIDOC
## Resolving the CupsClient

### Description
To get started, you will need to resolve the client out of the container.

### Code
```php
use Rawilk\Printing\Api\Cups\CupsClient;

$client = app(CupsClient::class, [
    'config' => [
        'ip' => 'your-ip',
        'username' => 'your-username',
        'password' => 'your-password',
        'port' => 631,
        'secure' => true,
    ],
]);
```

> Note: Providing the server credentials to the constructor here is optional, however it wil need to be set on the client manually before a request is made. The client will not resolve your credentials from the package's config file.
```

--------------------------------

### Publish Configuration File

Source: https://github.com/rawilk/laravel-printing/blob/main/README.md

Publish the package's configuration file to your application's config directory. This allows for customization of printing settings.

```bash
php artisan vendor:publish --tag="printing-config"
```

--------------------------------

### Implement PrintJob Interface

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/advanced-usage/custom-drivers.md

Create a PrintJob class implementing the PrintJob interface to represent a job sent to a printer. Include methods for job details like ID, name, and state.

```php
use Rawilk\Printing\Contracts\PrintJob as PrintJobContract;
use Carbon\CarbonInterface;

class PrintJob implements PrintJobContract
{
    public function date(): ?CarbonInterface {}

    public function id() {}

    public function name(): ?string {}

    public function printerId() {}

    public function printerName(): ?string {}

    public function state(): ?string {}

    public function toArray(): array {}
}
```

--------------------------------

### Retrieve All Computers

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/computer-service.md

Fetches a collection of all registered computers. Optional parameters for filtering and request options can be provided.

```php
Computer::all();
```

--------------------------------

### Request Options

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/api.md

Details how to use request options, particularly the `$opts` argument, to specify server credentials for individual requests.

```APIDOC
## Request Options

### Description
Most requests performed on the CUPS client accept request options, which can be used to set your server credentials on the request. Any time request options are supported, you can specify them through the `$opts` argument on method calls.

### Example
We recommend using an array, as the package will parse through that and create the `RequestOptions` object for you.

```php
$client->printJobs->create([...], opts: [
    'ip' => 'your-ip',
    'username' => 'your-username',
    'password' => 'your-password',
    'port' => 631,
    'secure' => true,
]);
```

> Tip: The `$opts` argument is accepted in most method calls to the api when using the `Printing` facade as well.
```

--------------------------------

### Configure Custom Driver

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/advanced-usage/custom-drivers.md

Add your custom driver configuration under the 'drivers' key in `config/printing`. Ensure the 'driver' key is set to 'custom' and provide any other necessary configuration.

```php
'driver' => 'my_custom_driver',

'drivers' => [
    ...
    'my_custom_driver' => [
        'driver' => 'custom', // This value is required
        // any other configuration needed
    ],
],
```

--------------------------------

### Request Options

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/api.md

Details how to pass request options, such as API keys and idempotency keys, to API calls.

```APIDOC
## Request Options

### Description
Most client requests accept an `$opts` argument for specifying request options like API keys or idempotency keys.

### Example
Creating a print job with request options:
```php
$client->printJobs->create([...], opts: [
    'api_key' => 'my-key',
    'idempotency_key' => 'foo',
]);
```

### Note
The `$opts` argument is also available when using the `Printing` facade.
```

--------------------------------

### Setting the API Key

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/api.md

Explains different methods for setting the API key for requests, including per-request options and global settings.

```APIDOC
## Setting the API Key

### Description
API keys can be set directly on the client, passed as request options, or set globally on the `PrintNode` class.

### Methods

1.  **Per-request options:**
    ```php
    $client->printers->retrieve($printerId, opts: ['api_key' => 'my-key']);
    ```

2.  **Globally on PrintNode class:**
    ```php
    use Rawilk\Printing\Api\PrintNode\PrintNode;

    PrintNode::setApiKey('my-key');
    ```

### Notes
*   API keys set on the client instance or via request options take precedence over the global setting.
*   When using the `Printing` facade, API keys can also be set globally, with package configuration taking precedence unless explicitly set to null.
```

--------------------------------

### Create and Send a Basic Print Task

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/basic-usage/print-tasks.md

Send a PDF file to a printer. Ensure the printer ID and file path are correctly specified.

```php
use Rawilk\Printing\Facades\Printing;

Printing::newPrintTask()
    ->printer($printerId)
    ->file('path_to_file.pdf')
    ->send();
```

--------------------------------

### Implement Printer Interface

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/advanced-usage/custom-drivers.md

Define a Printer class that implements the Printer interface to represent a physical printer. Include methods for capabilities, status, and jobs.

```php
use Illuminate\Support\Collection;
use Rawilk\Printing\Contracts\Printer as PrinterContract;

class Printer implements PrinterContract
{
    public function capabilities(): array {}

    public function description(): ?string {}

    public function id() {}

    public function isOnline() : bool {}

    public function name(): ?string {}

    public function status(): string {}

    public function trays(): array {}

    /**
     * @return Collection<int, \Rawilk\Printing\Contracts\PrintJob>
     */
    public function jobs(): Collection {}

    public function toArray(): array {}
}
```

--------------------------------

### Sending a Print Job with CUPS Server Credentials

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/print-task.md

Shows how to send a print job using the CUPS driver, specifying content type and optional CUPS server credentials for per-request authentication.

```php
use Rawilk\Printing\Api\Cups\Enums\ContentType;

Printing::newPrintTask()
    ->printer($printerId)
    ->content('hello world', ContentType::Plain)
    ->send([
        'ip' => '127.0.0.1',
        'username' => 'foo',
        'password' => 'bar',
        'port' => 631,
        'secure' => true,
    ]);
```

--------------------------------

### Retrieve a Computer by ID

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/computer-service.md

Fetches a specific computer resource using its unique ID. Optional parameters for request options are available.

```php
$computer = Computer::retrieve(100);
```

--------------------------------

### Retrieve a Set of Computers

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/computer-service.md

Fetches a collection of computers by providing an array of their IDs. This is useful for retrieving multiple specific computers at once.

```php
$computers = $client->computers->retrieveSet([1, 2, 3]);
```

--------------------------------

### Create Print Job with Request Options

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/api.md

When creating a print job, you can specify request options such as the API key and an idempotency key through the `$opts` argument. The package will parse the array into a `RequestOptions` object.

```php
$client->printJobs->create([...], opts: [
    'api_key' => 'my-key',
    'idempotency_key' => 'foo',
]);
```

--------------------------------

### Run Package Tests

Source: https://github.com/rawilk/laravel-printing/blob/main/README.md

Execute the package's test suite using Composer. This command runs all defined tests to ensure the package is functioning correctly.

```bash
composer test
```

--------------------------------

### Generate and Print a Receipt

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/advanced-usage/receipts.md

Generate a receipt string with various formatting options and then send it to a printer. Ensure the $receiptPrinterId and $text variables are properly set before sending.

```php
use Rawilk\Printing\Receipts\ReceiptPrinter;

// First generate the receipt
$receipt = (string) (new ReceiptPrinter)
    ->centerAlign()
    ->text('My heading')
    ->leftAlign()
    ->line()
    ->twoColumnText('Item 1', '2.00')
    ->twoColumnText('Item 2', '4.00')
    ->feed(2)
    ->centerAlign()
    ->barcode('1234')
    ->cut();

// Now send the string to your receipt printer
Printing::newPrintTask()
    ->printer($receiptPrinterId)
    ->content($text)
    ->send();
```

--------------------------------

### Configure Print Task Options

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/basic-usage/print-tasks.md

Set various options for a print job, such as job title, fitting to page, number of copies, and tray selection. Consult your print driver for available options.

```php
Printing::newPrintTask()
    ->printer($printerId)
    ->file('path_to_file.pdf')
    ->jobTitle('my job title')
    ->option('fit_to_page', true) // 'fit_to_page' is an available PrintNode option
    ->copies(2)
    ->tray('Tray 1') // check if your driver and printer supports this
    ->send();
```

--------------------------------

### all

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/computer-service.md

Retrieves all computers associated with your PrintNode account.

```APIDOC
## all

### Description
Retrieves all computers associated with your PrintNode account.

### Method
GET (assumed, based on common API patterns for 'all' operations)

### Endpoint
/computers

### Parameters
#### Query Parameters
- **$params** (array|null) - Optional - Additional parameters for filtering or pagination.
- **$opts** (null|array|RequestOptions) - Optional - Request options.

### Request Example
```php
$computers = $client->computers->all();
```

### Response
#### Success Response (200)
- **Collection<int, Rawilk\Printing\Api\PrintNode\Resources\Computer>** - A collection of computer resources.
```

--------------------------------

### Fetch All Computers

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/computer-service.md

Use this method to retrieve a collection of all computers associated with your PrintNode account. It accepts optional parameters for filtering or sorting.

```php
$computers = $client->computers->all();
```

--------------------------------

### Setting Server Credentials

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/api.md

Explains various methods for setting CUPS server credentials on the client, including request options and global configuration.

```APIDOC
## Setting Server Credentials

### Description
There are a few ways to set your CUPS server credentials for requests on the client.

### Method 1: Request Options
Another way is to set it using request options when calling a method on a Service.

```php
$client->printers->retrieve($printerId, opts: ['ip' => 'your-ip']);
```

### Method 2: Global Configuration
You may also choose to set the credentials on the `Cups` class itself. When the client does not detect a certain credential on the request, it will defer to this class for the value. This is typically done in a service provider in your application.

```php
use Rawilk\Printing\Api\Cups\Cups;

Cups::setIp('your-ip');
Cups::setAuth('your-username', 'your-password');
Cups::setPort(631);
Cups::setSecure(true);
```

> Note: Any credential set either on the client itself or passed through as a request option (via `$opts` arguments) will take precedence over this.

> Tip: You can also set credentials globally for CUPS like this when using the `Printing` facade. Keep in mind though the package configuration values will take precedence over this, unless you set them to `null` in the config.
```

--------------------------------

### Create and Send a New Print Job

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/basic-usage/basic-usage.md

Send a file to a specified printer by creating a new print task. Ensure the file path is correct.

```php
Printing::newPrintTask()
    ->printer($printerId)
    ->file('path_to_file.pdf')
    ->send();
```

--------------------------------

### Implement Custom Driver Interface

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/advanced-usage/custom-drivers.md

Your custom driver must implement the Driver interface and provide methods for managing print tasks, printers, and jobs. The constructor can accept configuration.

```php
use Illuminate\Support\Collection;
use Rawilk\Printing\Contracts\Driver;
use Rawilk\Printing\Contracts\Printer;
use Rawilk\Printing\Contracts\PrintJob;

class MyCustomDriver implements Driver
{
    public function __construct(protected array $config = [])
    {
    }

    public function newPrintTask(): PrintTask
    {
        return new PrintTask;
    }

    public function printer(
        $printerId = null,
    ): ?Printer {
        // ...
    }

    public function printers(
        ?int $limit = null,
        ?int $offset = null,
        ?string $dir = null,
    ): Collection {
        // ...
    }

    public function printJobs(
        ?int $limit = null,
        ?int $offset = null,
        ?string $dir = null,
    ): Collection {
        // ...
    }

    public function printJob(
        $jobId = null,
    ): ?PrintJob {
        // ...
    }

    /**
     * Return all jobs from a given printer.
     */
    public function printerPrintJobs(
        $printerId,
        ?int $limit = null,
        ?int $offset = null,
        ?string $dir = null,
    ): Collection {
        // ...
    }

    /**
     * Search for a print job from a given printer.
     */
    public function printerPrintJob(
        $printerId,
        $jobId,
    ): ?PrintJob {
        // ...
    }
}
```

--------------------------------

### create

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/printjob-service.md

Creates a new print job to be sent to a CUPS server for a physical printer. It accepts a PendingPrintJob object or a PendingRequest object, along with optional request options.

```APIDOC
## create

### Description

Create a new print job for CUPS to send to a physical printer.

### Method

POST

### Endpoint

/print-jobs

### Parameters

#### Path Parameters

None

#### Query Parameters

- **opts** (null|array|RequestOptions) - Optional - Additional request options.

#### Request Body

- **pendingJob** (Rawilk\Printing\Api\Cups\PendingPrintJob | Rawilk\Printing\Api\Cups\PendingRequest) - Required - An object representing the print job details.

### Request Example

```php
use Rawilk\Printing\Api\Cups\PendingPrintJob;
use Rawilk\Printing\Api\Cups\Enums\ContentType;

$pendingJob = PendingPrintJob::make()
    ->setContent('hello world')
    ->setContentType(ContentType::Plain)
    ->setPrinter($printerUri)
    ->setTitle('My job title')
    ->setSource(config('app.name'));

$printJob = $client->printJobs->create($pendingJob);
```

### Response

#### Success Response (200)

- **uri** (string) - The uri to the job.
- **jobUri** (string) - The uri to the job.
- **jobName** (string) - The name of the job.
- **jobPrinterUri** (string) - The uri to the printer the job was sent to.
- **jobState** (int) - An integer representation of the job's state.
- **dateTimeAtCreation** (string) - The date/time the job was created and sent to the printer.

#### Response Example

```json
{
  "uri": "http://localhost:631/jobs/123",
  "jobUri": "http://localhost:631/jobs/123",
  "jobName": "My job title",
  "jobPrinterUri": "http://localhost:631/printers/MyPrinter",
  "jobState": 3,
  "dateTimeAtCreation": "2023-10-27T10:00:00+00:00"
}
```
```

--------------------------------

### Resolve PrintNode Client from Container

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/upgrade.md

When singletons are removed, resolve the PrintNode client class from the container, passing configuration options if necessary.

```php
use Rawilk\Printing\Api\PrintNode\PrintNodeClient;

$client = app(PrintNodeClient::class, ['config' => ['api_key' => 'your-api-key']]);
```

--------------------------------

### Set Server Credentials via Request Options

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/api.md

Set CUPS server credentials for a specific request using the 'opts' argument. This takes precedence over globally set credentials.

```php
$client->printers->retrieve($printerId, opts: ['ip' => 'your-ip']);
```

--------------------------------

### Retrieve All Print Job States

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/printjob-service.md

Use the static `all` method to fetch a collection of all print job states. Optional parameters can be passed for filtering or request options.

```php
$states = PrintJobState::all();
```

--------------------------------

### List Available Printers

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/basic-usage/basic-usage.md

Retrieve a list of all available printers on your print server. Each printer object implements the Rawilk\Printing\Contracts\Printer interface.

```php
use Rawilk\Printing\Facades\Printing;

$printers = Printing::printers();

foreach ($printers as $printer) {
    echo $printer->name();
}
```

--------------------------------

### Pagination Parameters

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/api.md

Lists the supported parameters for paginating results from API requests.

```APIDOC
## Pagination Parameters

### Description
For paginatable requests, the following parameters can be passed via the `$params` argument.

### Supported Parameters
* `limit` (integer) - The maximum number of rows to return. Defaults to 100.
* `dir` (string) - Sort direction. Accepts `asc` (Ascending) or `desc` (Descending).
* `after` (integer) - A resource ID to use as an offset for pagination.

### Example
Retrieving computers with custom pagination:
```php
$client->computers->all([
    'limit' => 5,
    'dir' => 'desc',
    'after' => 1010,
]);
```

### Note
These pagination parameters can also be used with the `Printing` facade.
```

--------------------------------

### Implement PrintTask Class

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/advanced-usage/custom-drivers.md

Extend the base PrintTask class or implement the interface directly to handle the creation and sending of new print jobs. The send method should return a PrintJob instance.

```php
use Rawilk\Printing\PrintTask as BasePrintTask;

class PrintTask extends BasePrintTask
{
    public function send(): PrintJob {}
}
```

--------------------------------

### Send Print Job with Idempotency Key

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/print-task.md

Use the `send` method with an `idempotency_key` option to ensure a print job is processed only once, even if submitted multiple times.

```php
Printing::newPrintTask()
    ->printer($printerId)
    ->content('Hello world')
    ->send([
        'idempotency_key' => 'foo',
    ]);
```

--------------------------------

### Set Global API Key on PrintNode Class

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/api.md

Set a global API key on the `PrintNode` class. This key will be used if no API key is detected on the request. This is typically done in a service provider.

```php
use Rawilk\Printing\Api\PrintNode\PrintNode;

PrintNode::setApiKey('my-key');
```

--------------------------------

### Retrieve All Computers

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/computer-service.md

Fetches a collection of all computers registered with PrintNode. This method is a static call on the Computer resource.

```APIDOC
## Computer::all()

### Description
Retrieve all computers.

### Method
GET

### Endpoint
/computers

### Parameters
#### Query Parameters
- **params** (null|array) - Optional - Additional parameters for filtering or pagination.
- **opts** (null|array|RequestOptions) - Optional - Request options.

### Response
#### Success Response (200)
- **computers** (Collection<int, Rawilk\Printing\Api\PrintNode\Resources\Computer>) - A collection of Computer resources.
```

--------------------------------

### Set CUPS as Default Print Driver

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/overview.md

Configure the package to use the CUPS driver by default by setting the PRINTING_DRIVER environment variable.

```bash
PRINTING_DRIVER=cups
```

--------------------------------

### Send Print Job with API Key

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/print-task.md

Use the `send` method with an `api_key` option to authenticate a single print request.

```php
Printing::newPrintTask()
    ->printer($printerId)
    ->content('Hello world')
    ->send([
        'api_key' => 'my-key',
    ]);
```

--------------------------------

### create

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/printjob-service.md

Create a new print job for PrintNode to send to a physical printer. It is recommended to send a PendingPrintJob object.

```APIDOC
## create

### Description
Create a new print job for PrintNode to send to a physical printer. Note: although the `$params` argument accepts an array, it is recommended to send through a `PendingPrintJob` object instead.

### Method
POST (assumed based on common REST patterns for 'create' operations)

### Endpoint
/printjobs

### Parameters
#### Request Body
- **params** (array|PendingPrintJob) - Required - The print job details, preferably as a `PendingPrintJob` object.
- **opts** (null|array|RequestOptions) - Optional - Request options.

### Request Example
```php
use Rawilk\Printing\Api\PrintNode\PendingPrintJob;
use Rawilk\Printing\Api\PrintNode\Enums\ContentType;

$pendingJob = PendingPrintJob::make()
    ->setContent('hello world')
    ->setContentType(ContentType::RawBase64)
    ->setPrinter($printerId)
    ->setTitle('My job title')
    ->setSource(config('app.name'));

$printJob = $client->printJobs->create($pendingJob);
```

### Response
#### Success Response (200)
- **PrintJob** - The created PrintJob resource.
```

--------------------------------

### Register Custom Driver in Service Provider

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/advanced-usage/custom-drivers.md

Extend the print factory within a service provider to register your custom driver. The first parameter must match the 'driver' key in your configuration.

```php
use Rawilk\Printing\Factory;

public function register(): void
{
    $this->app[Factory::class]->extend('custom', function (array $config) {
        return new MyCustomDriver($config);
    });
}
```

--------------------------------

### retrieve

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/computer-service.md

Retrieve a specific computer from the API by its ID.

```APIDOC
## retrieve

### Description
Retrieve a computer from the API by its ID.

### Method
GET (assumed, based on common API patterns for 'retrieve' operations)

### Endpoint
/computers/{id}

### Parameters
#### Path Parameters
- **$id** (int) - Required - The computer's ID.

#### Query Parameters
- **$params** (array|null) - Optional - Not applicable to this request.
- **$opts** (null|array|RequestOptions) - Optional - Request options.

### Response
#### Success Response (200)
- **Rawilk\Printing\Api\PrintNode\Resources\Computer** - The requested computer resource.
```

--------------------------------

### Paginate Computer Resources

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/api.md

For paginated requests, use the `$params` argument to specify pagination parameters like `limit`, `dir` (direction), and `after` (resource ID offset).

```php
$client->computers->all([
    'limit' => 5,
    'dir' => 'desc',
    'after' => 1010,
]);
```

--------------------------------

### Set API Key via Request Options

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/api.md

Set the API key for a specific request using the `opts` argument when calling a service method. This takes precedence over other API key settings.

```php
$client->printers->retrieve($printerId, opts: ['api_key' => 'my-key']);
```

--------------------------------

### Retrieve All Printers

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/api.md

Use the 'printers' service class on the client to retrieve a list of all available printers.

```php
$client->printers->all();
```

--------------------------------

### Setting Print Job Options with OperationAttribute

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/print-task.md

Demonstrates how to set specific CUPS options for a print job, such as the number of copies, using the OperationAttribute enum.

```php
use Rawilk\Printing\Api\Cups\Enums\OperationAttribute;
use Rawilk\Printing\Facades\Printing;

Printing::newPrintTask()
    ->option(
        OperationAttribute::Copies,
        OperationAttribute::Copies->toType(2),
    );
```

--------------------------------

### Retrieve a Single Computer

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/computer-service.md

Fetches a specific computer from the API using its unique ID. The `$params` argument is not applicable for this request.

```php
$computer = $client->computers->retrieve(123);
```

--------------------------------

### deleteMany

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/computer-service.md

Delete a set of computers by their IDs. Omit or use an empty array to delete all computers.

```APIDOC
## deleteMany

### Description
Delete a set of computers by their IDs. Omit or use an empty array of `$ids` to delete all computers. Method will return an array of affected IDs.

### Method
DELETE (assumed, based on common API patterns for bulk deletion)

### Endpoint
/computers

### Parameters
#### Query Parameters
- **$ids** (array) - Optional - The IDs of the computers to delete. If omitted or empty, all computers are deleted.
- **$params** (array|null) - Optional - Additional parameters.
- **$opts** (null|array|RequestOptions) - Optional - Request options.

### Response
#### Success Response (200)
- **array** - An array of affected computer IDs.
```

--------------------------------

### retrieveSet

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/computer-service.md

Retrieve a specific set of computers by their IDs.

```APIDOC
## retrieveSet

### Description
Retrieve a specific set of computers by their IDs.

### Method
GET (assumed, based on common API patterns for retrieving multiple resources)

### Endpoint
/computers

### Parameters
#### Query Parameters
- **$ids** (array) - Required - The IDs of the computers to retrieve.
- **$params** (array|null) - Optional - Additional parameters.
- **$opts** (null|array|RequestOptions) - Optional - Request options.

### Response
#### Success Response (200)
- **Collection<int, Rawilk\Printing\Api\PrintNode\Resources\Computer>** - A collection of the requested computer resources.
```

--------------------------------

### Retrieve All Printers

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/printer-service.md

Fetch a collection of all available printers using the static `all` method. Optional parameters can be provided for filtering or request options.

```php
$printers = Printer::all();
```

--------------------------------

### Set PrintNode API Key at Runtime

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/overview.md

Configure the PrintNode API key programmatically at runtime. This is useful for multi-tenant applications or dynamic credential management.

```php
use Rawilk\Printing\Api\PrintNode\PrintNode;

PrintNode::setApiKey('your-api-key');
```

--------------------------------

### Printer Resource State Reasons

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/printer-service.md

Retrieves detailed reasons for the printer's current state, if any are provided.

```APIDOC
## stateReasons

### Description
If any reasons are provided for the printer's state, this will return a collection of enums that represent the reason for the printer's state.

### Method Signature
`stateReasons(): Collection<int, Rawilk\Printing\Api\Cups\Enums\PrinterStateReason>

### Example Usage
```php
$reasons = $printer->stateReasons();
```
```

--------------------------------

### Conditionally Apply Formatting

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/advanced-usage/receipts.md

Use the 'when' method to conditionally apply formatting to the receipt. This is useful for applying changes based on certain conditions.

```php
$receipt = (string) (new ReceiptPrinter)
    ->text('foo')
    ->when(
        $someCondition === true,
        fn (ReceiptPrinter $printer) => $printer->centerAlign()
    );
```

--------------------------------

### Set PrintNode as Default Print Driver in .env

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/overview.md

Configure the package to use the PrintNode driver by default by setting the PRINTING_DRIVER environment variable.

```bash
PRINTING_DRIVER=printnode
```

--------------------------------

### Retrieve a Specific Computer

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/computer-service.md

Retrieves a single computer resource by its unique ID. This is a static method available on the Computer resource.

```APIDOC
## Computer::retrieve(int $id)

### Description
Retrieve a computer with a given id.

### Method
GET

### Endpoint
/computers/{id}

### Parameters
#### Path Parameters
- **id** (int) - Required - The unique identifier of the computer.
#### Query Parameters
- **params** (null|array) - Optional - Additional parameters.
- **opts** (null|array|RequestOptions) - Optional - Request options.

### Response
#### Success Response (200)
- **computer** (Rawilk\Printing\Api\PrintNode\Resources\Computer) - The requested Computer resource.
```

--------------------------------

### ReceiptPrinter Methods

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/advanced-usage/receipts.md

Reference for the methods available on the ReceiptPrinter class.

```APIDOC
## ReceiptPrinter Methods

### centerAlign()

Center align any new text.

### leftAlign()

Left align any new text.

### rightAlign()

Right align any new text.

### leftMargin(int $margin = 0)

Set the left margin for any new text. The unit for the margin will be `dots`.

### lineHeight(int|null $height = null)

Set the line height for any new text. The unit for the line height will be `dots`. Use `null` or omit the `$height` parameter to reset the line height to the printer's defaults for any new text.

### text(string $text, bool $insertNewLine = true)

Write a line of text to the receipt. Set `$insertNewLine` to `false` to prevent a newline character from being added.

### twoColumnText(string $left, string $right)

Insert a line of text split into two columns, left and right justified. Useful for stuff like writing a line item and its price on a line.

### barcode(string $barcodeContent, int $type = \Mike42\Escpos\Printer::BARCODE_CODE39)

Print a barcode to the receipt. The `$type` parameter defaults to `BARCODE_CODE39`.

### line()

Print a line across the receipt using the `-` character.

### doubleLine()

Print a line across the receipt using the `=` character.

### cut(int $mode = \Mike42\Escpos\Printer::CUT_FULL, int $lines = 3)

Instruct the receipt printer to cut the paper. Can be called multiple times. The `$mode` parameter defaults to `CUT_FULL` and `$lines` to `3`.

### feed(int $lines = 1)

Feed an empty line(s) to the receipt printer. Defaults to feeding 1 line.

### close()

Close the connection to the receipt printer. This is automatically called.
```

--------------------------------

### Set PrintNode API Key on Driver Instance

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/upgrade.md

Update the API key directly on the PrintNode driver instance. This method is less recommended but remains an option.

```php
Printing::driver('printnode')->getDriver()->setApiKey('my-key');
```

--------------------------------

### Update PrintTask Interface Signature

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/upgrade.md

If you have a custom driver, update the `option()` method signature on the `PrintTask` interface to support enums for option keys.

```php
public function option(BackedEnum|string $key, $value): self;
```

--------------------------------

### Resolve Printing Factory from Container

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/upgrade.md

Resolve the printing factory instance from the container using its class name.

```php
use Rawilk\Printing\Factory;

// printing.factory
app(Factory::class);
```

--------------------------------

### Printer::all()

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/printer-service.md

Retrieve all printers available in the PrintNode system. This static method allows fetching a collection of all registered printers.

```APIDOC
## Printer::all()

### Description
Retrieve all printers.

### Method
GET

### Endpoint
/printers

### Parameters
#### Query Parameters
- **$params** (array) - Optional - Additional parameters for filtering or pagination.
- **$opts** (array|RequestOptions) - Optional - Request options.

### Response
#### Success Response (200)
- **Collection<int, Printer>** - A collection of Printer objects.
```

--------------------------------

### Conditionable Receipts

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/advanced-usage/receipts.md

Demonstrates using the `when` method for conditional receipt formatting.

```APIDOC
## Conditionable Receipts

### Description
The `ReceiptPrinter` class implements the `Conditionable` trait, allowing you to conditionally apply formatting methods using the `when` method.

### Code Example
```php
$receipt = (string) (new ReceiptPrinter)
    ->text('foo')
    ->when(
        $someCondition === true,
        fn (ReceiptPrinter $printer) => $printer->centerAlign()
    );
```

### Notes
- The `when` method accepts a condition and a closure that receives the `ReceiptPrinter` instance if the condition is true.
```

--------------------------------

### Retrieve All Print Job States

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/printjob-service.md

Fetches all print job states for an account. A `limit` parameter can be included in `$params` to control the number of print jobs whose states are retrieved.

```php
// Example usage for states method would go here, but is not provided in the source.
```

--------------------------------

### Retrieve a Printer by ID

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/printer-service.md

Fetch a specific printer by its unique ID using the static `retrieve` method. Optional parameters can be passed for request options.

```php
$printer = Printer::retrieve(100);
```

--------------------------------

### PrintJob Parameters for Printer

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/entities.md

Use the `$params` argument to limit and sort the print jobs retrieved for a printer instance. Supported values include 'limit', 'after' for pagination, and 'dir' for sort order.

```php
$params = [
    'limit' => 3,
    'after' => 1, // a job id to offset the results by for pagination
    'dir' => 'asc', // or 'desc'
];
```

--------------------------------

### Use PrintNode Driver for Specific Requests

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/overview.md

Explicitly select the PrintNode driver for individual print tasks. This allows for flexible driver selection within your application.

```php
use Rawilk\Printing\Facades\Printing;
use Rawilk\Printing\Enums\PrintDriver;

Printing::driver(PrintDriver::PrintNode)->newPrintTask();
```

--------------------------------

### Set CUPS Driver for Specific Requests

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/overview.md

Alternatively, you can specify the CUPS driver for individual print tasks using the Printing facade.

```php
use Rawilk\Printing\Facades\Printing;
use Rawilk\Printing\Enums\PrintDriver;

Printing::driver(PrintDriver::Cups)->newPrintTask();
```

--------------------------------

### Set PrintNode API Key via Request Option

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/upgrade.md

Pass the API key as an option when sending a print task or interacting with a printer. Note that PHP's named arguments cannot be used here.

```php
Printing::newPrintTask()
    ->printer($printerId)
    ->content('hello world')
    ->send(['api_key' => 'my-key']);

// Also works with other method calls
Printing::printer($printerId, [], ['api_key' => 'my-key']);
```

--------------------------------

### Print Raw Text Content

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/advanced-usage/raw-content-printing.md

Use the `content()` method to send a string of raw text to the printer. This is ideal for printing receipts. Ensure your printer driver supports raw text printing.

```php
Printing::newPrintTask()
    ->printer($printerId)
    ->content('hello world')
    ->send();
```

--------------------------------

### Retrieve a Print Job by URI

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/cups/printjob-service.md

Retrieve a specific print job from the CUPS server using its unique URI. Optional parameters can be provided for filtering or additional options.

```php
$printJob = $client->printJobs->retrieve($uri);
```

--------------------------------

### all

Source: https://github.com/rawilk/laravel-printing/blob/main/docs/printnode/printjob-service.md

Retrieve all print jobs associated with a PrintNode account.

```APIDOC
## all

### Description
Retrieve all print jobs associated with a PrintNode account.

### Method
GET (assumed based on common REST patterns for 'all' operations)

### Endpoint
/printjobs

### Parameters
#### Query Parameters
- **params** (array|null) - Optional - Additional parameters for filtering or pagination.
- **opts** (null|array|RequestOptions) - Optional - Request options.

### Response
#### Success Response (200)
- **Collection<int, PrintJob>** - A collection of PrintJob resources.
```