> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/packages/service/usage.md).

# Usage

## Create a service class

```php
namespace App\Modules\Billing\Services;

use Quantum\Service\Service;

class InvoiceService extends Service
{
    public function send(int $invoiceId): void
    {
        // business logic
    }
}
```

Resolve service classes from subclasses of `Quantum\Service\Service`.

## Resolve a fresh instance

```php
use App\Modules\Billing\Services\InvoiceService;

$service = service(InvoiceService::class);
$service->send(15);
```

Use this when each call should get its own instance.

## Resolve a shared instance

```php
$service = service(InvoiceService::class, true);
```

Use shared mode when the same service instance should be reused. The shared cache key is the service class name.

## Pass runtime constructor arguments

Use the factory directly when constructor values are runtime-specific:

```php
use Quantum\Service\Factories\ServiceFactory;

$service = ServiceFactory::create(InvoiceService::class, [
    'tenantId' => $tenantId,
]);
```

`service()` does not accept custom constructor args. For shared services, provide runtime args on the first `ServiceFactory::get()` call that creates the instance.

## Compose services with DI

```php
class InvoiceService extends Service
{
    public function __construct(
        private MailerService $mailer,
        private InvoiceRepository $invoices,
    ) {
    }
}
```

Constructor dependencies are resolved through DI.

## Common pitfalls

### Passing a non-service class

```php
service(stdClass::class);
```

This call is accepted for subclasses of `Quantum\Service\Service`. Use a concrete service class here.

### Forgetting shared mode

If you expect reuse, pass `true` explicitly.

### Relying on undefined methods

Typos like `$service->publsih()` raise an exception immediately.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://quantumphp.gitbook.io/docs/packages/service/usage.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.