PHPackages                             square1/pwned-check - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Security](/categories/security)
4. /
5. square1/pwned-check

ActiveLibrary[Security](/categories/security)

square1/pwned-check
===================

Validate password changes against known-compromised passwords

1.2(3y ago)838.3k—0%21MITPHPPHP >=7.0

Since Mar 11Pushed 3y ago5 watchersCompare

[ Source](https://github.com/square1-io/pwned-check)[ Packagist](https://packagist.org/packages/square1/pwned-check)[ Docs](https://github.com/square1-io/pwned-check)[ RSS](/packages/square1-pwned-check/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (1)Versions (5)Used By (1)

Pwned Check
===========

[](#pwned-check)

PHP utility class to check whether a given password is a known compromised password, using the [Pwned Passwords](https://haveibeenpwned.com/Passwords) service provided by [Troy Hunt](https://www.troyhunt.com/).

Install
-------

[](#install)

Via Composer

```
$ composer require square1/pwned-check
```

Usage
-----

[](#usage)

```
    use Square1\Pwned\Pwned;
    use Square1\Pwned\Exception\ConnectionFailedException;

    $password = 'password1';

    $pwned = new Pwned();
    // Has password ever been compromised?
    $compromised = $pwned->hasBeenPwned($password);
    // (bool) true

    // Has password appeared in more than 5 compromised datasets?
    $compromised = $pwned->hasBeenPwned($password, 5);

    // Don't allow remote server to hang for over 2 seconds
    try {
        $pwned = new Pwned(['remote_processing_timeout' => 2]);
        $compromised = $pwned->hasBeenPwned($password);
    } catch (ConnectionFailedException $e) {
       // Connection has timed out..
    }
```

Options
-------

[](#options)

A number of constructor options are available to modify the behaviour of the class.

OptionDefaultComment`endpoint``https://api.pwnedpasswords.com/range/`Service endpoint url`user_agent``Square1 Pwned PHP package`User agent to use - api calls without a user agent are rejected`connection_timeout``0`Initial curl connection limit (0 for off). If connection takes longer than X seconds to establish, it's terminated`remote_processing_timeout``0`Number of seconds after which to kill a slow-responding connection (0 for off)`minimum_occurrences``1`Minimum number of times a password needs to appear in breaches before being considered compromisedFAQ
---

[](#faq)

### How do you decide if a password is "known compromised"?

[](#how-do-you-decide-if-a-password-is-known-compromised)

The [Pwned Passwords](https://haveibeenpwned.com/Passwords) service provided by [Troy Hunt](https://www.troyhunt.com/) is a great resource that aggregates passwords found in known data breaches. The api allows us to check whether a password has appeared in previous data breaches, and also how frequently it shows up. The frequency allows us to decide how strict we want to be when deciding if a password is to be considered compromised. For example, `abcd1234` may show up 334,000 times in data breaches, while `totallyuniqueandrandompass1234` may only show up once. Depending on your use case, it may be appropriate to only blacklist widely compromised passwords. The frequency count is what allows us to do this.

### Does sending a password to the service not constitute a security risk?

[](#does-sending-a-password-to-the-service-not-constitute-a-security-risk)

The Pwned password api allows for range queries to be made. This involves hashing the password via this library within your application, and sending a partial section of it to the api. The api returns a set of password hashes (and frequency counts for each). These can then be matched against the full password hash, which never needs to leave the application. Cloudflare worked closely with Troy on the design of this api, and go into a lot more detail on this approach to using k-anonymity in [this blog post](https://blog.cloudflare.com/validating-leaked-passwords-with-k-anonymity/).

### What if the api server is slow to respond? Will my app have problems?

[](#what-if-the-api-server-is-slow-to-respond-will-my-app-have-problems)

Typical api responses are blazingly-fast - the article [here](https://www.troyhunt.com/i-wanna-go-fast-why-searching-through-500m-pwned-passwords-is-so-quick/) is worth a read. However, it's possible that at some point there'll be a connection issue or some other performance issue with the service. To protect your app in these cases, you can set the `connection_timeout` and `remote_processing_timeout` values. These are the seconds to wait before killing a curl connection and wait time after connection respectively. If the service call is terminated due to one of these timeouts being reached, a `Square1\Pwned\Exception\ConnectionFailedException` will be thrown.

### Are the api results cached?

[](#are-the-api-results-cached)

This code is intended to be framework-agnostic, so caching is left to your application layer.

Testing
-------

[](#testing)

```
$ composer test
```

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity35

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~855 days

Total

3

Last Release

1281d ago

PHP version history (2 changes)1.0PHP ~7.0

1.2PHP >=7.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/5a6096b0455d662c5963ed82e1f0968bc4a18bdfedd332f7fd2598480b4c17bd?d=identicon)[conroyp](/maintainers/conroyp)

---

Top Contributors

[![conroyp](https://avatars.githubusercontent.com/u/143244?v=4)](https://github.com/conroyp "conroyp (6 commits)")

---

Tags

securitypasswordsquare1pwned-check

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/square1-pwned-check/health.svg)

```
[![Health](https://phpackages.com/badges/square1-pwned-check/health.svg)](https://phpackages.com/packages/square1-pwned-check)
```

###  Alternatives

[rych/phpass

PHP Password Library: Easy, secure password management for PHP

248801.7k4](/packages/rych-phpass)[bordoni/phpass

Portable PHP password hashing framework

244.4M26](/packages/bordoni-phpass)[jeremykendall/password-validator

Password Validator validates password\_hash generated passwords, rehashes passwords as necessary, and will upgrade legacy passwords.

14469.9k3](/packages/jeremykendall-password-validator)[mxrxdxn/pwned-passwords

A library to query Troy Hunt's Pwned Passwords service to see whether or not a password has been included in a public breach.

3270.9k2](/packages/mxrxdxn-pwned-passwords)[spooner-web/be_secure_pw

You can set password conventions to force secure passwords for BE users.

10461.3k](/packages/spooner-web-be-secure-pw)[firehed/security

Security tools for PHP

2374.9k2](/packages/firehed-security)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)