{"id":23359773,"url":"https://github.com/firehed/psr-clock","last_synced_at":"2025-04-07T20:46:07.157Z","repository":{"id":229883650,"uuid":"777876656","full_name":"Firehed/psr-clock","owner":"Firehed","description":"PSR Clock implementation with controls for use in tests","archived":false,"fork":false,"pushed_at":"2024-03-27T18:45:21.000Z","size":8,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-13T22:26:58.614Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Firehed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-26T17:05:56.000Z","updated_at":"2024-03-26T17:06:02.000Z","dependencies_parsed_at":"2024-12-21T11:12:08.597Z","dependency_job_id":"cb6eb3c9-9a58-4ac6-9ed3-fbf2fcc556d7","html_url":"https://github.com/Firehed/psr-clock","commit_stats":null,"previous_names":["firehed/psr-clock"],"tags_count":1,"template":false,"template_full_name":"Firehed/php-library-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Firehed%2Fpsr-clock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Firehed%2Fpsr-clock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Firehed%2Fpsr-clock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Firehed%2Fpsr-clock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Firehed","download_url":"https://codeload.github.com/Firehed/psr-clock/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247729465,"owners_count":20986392,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-21T11:11:56.029Z","updated_at":"2025-04-07T20:46:06.948Z","avatar_url":"https://github.com/Firehed.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Clock\n\nA [PSR-20](https://www.php-fig.org/psr/psr-20/) Clock implementation, with time configuration and movement support for use in unit tests.\n\n[![Test](https://github.com/Firehed/psr-clock/actions/workflows/test.yml/badge.svg)](https://github.com/Firehed/psr-clock/actions/workflows/test.yml)\n[![Static analysis](https://github.com/Firehed/psr-clock/actions/workflows/static-analysis.yml/badge.svg)](https://github.com/Firehed/psr-clock/actions/workflows/static-analysis.yml)\n[![Lint](https://github.com/Firehed/psr-clock/actions/workflows/lint.yml/badge.svg)](https://github.com/Firehed/psr-clock/actions/workflows/lint.yml)\n[![codecov](https://codecov.io/gh/Firehed/psr-clock/graph/badge.svg?token=YHmKp3PzwF)](https://codecov.io/gh/Firehed/psr-clock)\n\n## Installation\n```\ncomposer require firehed/clock\n```\n\n## Usage\n\nGenerally speaking, `ClockInterface` is only useful when paired with Dependency Injection.\nThis allows unit tests to provide a test clock set to a specific point in time, where the actual application is wired to use a wall clock and follows real time.\n\n### Wall Clock\n\nA wall clock will return the current system time any time `-\u003enow()` is called.\nIt advances normally and behaves identically to calling `time()` or `new DateTimeImmutable()` directly would.\n\n**This is what you should use in actual application code.**\n\n```php\nuse Firehed\\Clock\\Clock;\n\n$clock = new Clock();\n```\n\n\u003e [!IMPORTANT]\n\u003e A clock in \"wall clock\" mode cannot be moved, and will throw an exception if you attempt to do so.\n\n### Test Clock\n\nA test clock will return a specified time, and can be manually moved.\nIt will _not_ advance automatically as actual wall time progresses (e.g. is unaffected by `sleep()`, etc).\nThis is intended for use in test cases, such as:\n\n- Validating or adjusting date ranges in queries\n- Ensuring that expiration behavior works as expected\n- Verifying rate-limiting behavior\n\nBasically, if you'd normally have to use `sleep()` to check something, you can instead move the test clock by a specificed amount or to a specified time and continue the test case _as if_ that time had passed.\nThis can result in tests that run faster and more reliably, without having to fuss with \"give or take a second\" logic.\n\n```php\nuse Firehed\\Clock\\Clock;\n\n$clock = new Clock($timeOrOffset);\n\n// ...\n\n$clock-\u003emoveTo($otherTimeOrOffset);\n```\n\nThe behavior of `$timeOrOffset` and `$otherTimeOrOffset` is as follows:\n\nType | `__construct` Behavior | `moveTo()` behavior\n--- | --- | ---\n`DateTimeInterface` | The clock will be fixed to the specified time | The clock will move to the specified time\n`DateInterval` | The clock will be fixed to the system time _when construct is called_, plus the offset | The clock will advance by the offset from its initial fixed time\n`string` that starts with `P` | The string will be parsed as a `DateInterval` and behave as above | Same\n`string` | The clock will be fixed to an equivalent of `strtotime(string)` | Same\n`int` or `float` | The value will be interpreted as a Unix timestamp and fixed to that time | Same\nAnything else | A `TypeError` will be thrown | Same\n\n\u003e [!WARNING]\n\u003e `float` values can _and often do_ lose precision at timestamps near the current time.\n\u003e If your test needs sub-second behavior, prefer any of the more-specific formats.\n\u003e\n\u003e Unixtime strings avoid floating point precision issues.\n\u003e These are `@` followed by the timestamp; e.g. `'@1234567890.987654'`\n\nThe library does **not** make guarantees about subsequent calls to -\u003enow() on a test clock being the same or different `DateTimeImmutable` instances.\nHowever, they are guaranteed to be in reference to the same point in time.\n\n\u003e [!TIP]\n\u003e If you only care about relative movement, a test clock can be set up as `new Clock('now')`.\n\u003e You may also use only small values near the Unix epoch (e.g. `0`, `20`); if your application uses `ClockInterface` consistently it should still work, and run as if the current time was in 1970.\n\n#### Moving the clock backwards\nRelative time changes always use `DateTimeImmutable-\u003eadd()` or the equivalent internally.\n\nTo move the clock backwards:\n- Pass a `DateInterval` where `invert` is set to `1`\n- Pass any absolute timestamp equivalent before the currently-set value\n\n### Time Zones\n\nThis library does not currently aim to handle any time zone specifics, and will default to the system configuration.\nIf your needs include specific behavior regarding time zones, be sure to provide values that include time zone information.\n\n## Contributing\n\nPlease report any bugs or feature requests on GitHub.\nBe aware that this is considered _mostly_ feature-complete, so feature requests may be declined.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirehed%2Fpsr-clock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirehed%2Fpsr-clock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirehed%2Fpsr-clock/lists"}