> 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/hasher/usage.md).

# Usage

Use `Quantum\Hasher\Hasher` directly when you need password hashing behavior without the higher-level Auth package.

## Hashing and verifying a password

```php
use Quantum\Hasher\Hasher;

$hasher = new Hasher();

$hash = $hasher->hash('secret');

if ($hasher->check('secret', $hash)) {
    // password matches
}
```

A new instance uses bcrypt with cost `12` by default.

## Lowering the cost in tests or local tooling

Quantum's own tests reduce the cost before hashing so password operations run faster:

```php
$hasher = (new Hasher())->setCost(4);
$hash = $hasher->hash('secret');
```

That pattern is reasonable for tests. Do not copy it into production unless you intentionally want weaker bcrypt work factors.

## Detecting when a stored hash should be upgraded

```php
$hasher = (new Hasher())->setCost(4);
$hash = $hasher->hash('secret');

$hasher->setCost(5);

if ($hasher->needsRehash($hash)) {
    $hash = $hasher->hash('secret');
}
```

This is the normal upgrade path:

1. verify the password with `check()`
2. call `needsRehash()` against the stored hash
3. write a new hash if the current settings require it

## Switching algorithms

```php
$hasher = (new Hasher())
    ->setAlgorithm(PASSWORD_DEFAULT);

$hash = $hasher->hash('secret');
```

If you need to change both the algorithm and the cost, set the algorithm first:

```php
$hasher = (new Hasher())
    ->setAlgorithm(PASSWORD_BCRYPT)
    ->setCost(12);
```

Keep two caveats in mind:

* `setAlgorithm()` does not validate the algorithm name itself
* `setCost()` only enforces range checks when the current algorithm is `PASSWORD_BCRYPT`

## Inspecting current settings

```php
$hasher = (new Hasher())->setCost(4);

$currentAlgorithm = $hasher->getAlgorithm();
$currentCost = $hasher->getCost();
```

These getters show the object's active settings. They do not read anything from a stored password hash.

## Inspecting stored hash metadata

```php
$hasher = (new Hasher())->setCost(4);
$hash = $hasher->hash('secret');

$info = $hasher->info($hash);
```

The returned array is the raw output from PHP's `password_get_info()`. In Quantum's tests, the package expects keys such as `algoName` to be present.

## Recommended usage pattern

For login flows:

* use `check()` to verify the submitted password
* use `needsRehash()` after a successful match
* use a new `hash()` only when the password is first stored or upgraded

If you already use Quantum's Auth package, let that package own the hasher lifecycle instead of sharing one mutable `Hasher` object across unrelated code.


---

# 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/hasher/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.