{"id":13616545,"url":"https://github.com/doctrine/deprecations","last_synced_at":"2025-05-14T22:06:10.601Z","repository":{"id":37945937,"uuid":"278726910","full_name":"doctrine/deprecations","owner":"doctrine","description":"Thin library around different deprecation strategies","archived":false,"fork":false,"pushed_at":"2025-04-07T20:12:43.000Z","size":162,"stargazers_count":1749,"open_issues_count":5,"forks_count":18,"subscribers_count":10,"default_branch":"1.1.x","last_synced_at":"2025-05-06T13:38:10.893Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://doctrine-project.org","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/doctrine.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,"zenodo":null}},"created_at":"2020-07-10T20:26:32.000Z","updated_at":"2025-05-06T08:14:31.000Z","dependencies_parsed_at":"2025-04-18T23:23:29.668Z","dependency_job_id":"a712b3ed-ce61-435d-a1e7-5d88edf4c1f9","html_url":"https://github.com/doctrine/deprecations","commit_stats":{"total_commits":75,"total_committers":15,"mean_commits":5.0,"dds":0.52,"last_synced_commit":"dfbaa3c2d2e9a9df1118213f3b8b0c597bb99fab"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doctrine%2Fdeprecations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doctrine%2Fdeprecations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doctrine%2Fdeprecations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doctrine%2Fdeprecations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/doctrine","download_url":"https://codeload.github.com/doctrine/deprecations/tar.gz/refs/heads/1.1.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252851883,"owners_count":21814236,"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-08-01T20:01:30.003Z","updated_at":"2025-05-07T09:35:55.458Z","avatar_url":"https://github.com/doctrine.png","language":"PHP","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"# Doctrine Deprecations\n\nA small (side-effect free by default) layer on top of\n`trigger_error(E_USER_DEPRECATED)` or PSR-3 logging.\n\n- no side-effects by default, making it a perfect fit for libraries that don't know how the error handler works they operate under\n- options to avoid having to rely on error handlers global state by using PSR-3 logging\n- deduplicate deprecation messages to avoid excessive triggering and reduce overhead\n\nWe recommend to collect Deprecations using a PSR logger instead of relying on\nthe global error handler.\n\n## Usage from consumer perspective:\n\nEnable Doctrine deprecations to be sent to a PSR3 logger:\n\n```php\n\\Doctrine\\Deprecations\\Deprecation::enableWithPsrLogger($logger);\n```\n\nEnable Doctrine deprecations to be sent as `@trigger_error($message, E_USER_DEPRECATED)`\nmessages by setting the `DOCTRINE_DEPRECATIONS` environment variable to `trigger`.\nAlternatively, call:\n\n```php\n\\Doctrine\\Deprecations\\Deprecation::enableWithTriggerError();\n```\n\nIf you only want to enable deprecation tracking, without logging or calling `trigger_error`\nthen set the `DOCTRINE_DEPRECATIONS` environment variable to `track`.\nAlternatively, call:\n\n```php\n\\Doctrine\\Deprecations\\Deprecation::enableTrackingDeprecations();\n```\n\nTracking is enabled with all three modes and provides access to all triggered\ndeprecations and their individual count:\n\n```php\n$deprecations = \\Doctrine\\Deprecations\\Deprecation::getTriggeredDeprecations();\n\nforeach ($deprecations as $identifier =\u003e $count) {\n    echo $identifier . \" was triggered \" . $count . \" times\\n\";\n}\n```\n\n### Suppressing Specific Deprecations\n\nDisable triggering about specific deprecations:\n\n```php\n\\Doctrine\\Deprecations\\Deprecation::ignoreDeprecations(\"https://link/to/deprecations-description-identifier\");\n```\n\nDisable all deprecations from a package\n\n```php\n\\Doctrine\\Deprecations\\Deprecation::ignorePackage(\"doctrine/orm\");\n```\n\n### Other Operations\n\nWhen used within PHPUnit or other tools that could collect multiple instances of the same deprecations\nthe deduplication can be disabled:\n\n```php\n\\Doctrine\\Deprecations\\Deprecation::withoutDeduplication();\n```\n\nDisable deprecation tracking again:\n\n```php\n\\Doctrine\\Deprecations\\Deprecation::disable();\n```\n\n## Usage from a library/producer perspective:\n\nWhen you want to unconditionally trigger a deprecation even when called\nfrom the library itself then the `trigger` method is the way to go:\n\n```php\n\\Doctrine\\Deprecations\\Deprecation::trigger(\n    \"doctrine/orm\",\n    \"https://link/to/deprecations-description\",\n    \"message\"\n);\n```\n\nIf variable arguments are provided at the end, they are used with `sprintf` on\nthe message.\n\n```php\n\\Doctrine\\Deprecations\\Deprecation::trigger(\n    \"doctrine/orm\",\n    \"https://github.com/doctrine/orm/issue/1234\",\n    \"message %s %d\",\n    \"foo\",\n    1234\n);\n```\n\nWhen you want to trigger a deprecation only when it is called by a function\noutside of the current package, but not trigger when the package itself is the cause,\nthen use:\n\n```php\n\\Doctrine\\Deprecations\\Deprecation::triggerIfCalledFromOutside(\n    \"doctrine/orm\",\n    \"https://link/to/deprecations-description\",\n    \"message\"\n);\n```\n\nBased on the issue link each deprecation message is only triggered once per\nrequest.\n\nA limited stacktrace is included in the deprecation message to find the\noffending location.\n\nNote: A producer/library should never call `Deprecation::enableWith` methods\nand leave the decision how to handle deprecations to application and\nframeworks.\n\n## Usage in PHPUnit tests\n\nThere is a `VerifyDeprecations` trait that you can use to make assertions on\nthe occurrence of deprecations within a test.\n\n```php\nuse Doctrine\\Deprecations\\PHPUnit\\VerifyDeprecations;\n\nclass MyTest extends TestCase\n{\n    use VerifyDeprecations;\n\n    public function testSomethingDeprecation()\n    {\n        $this-\u003eexpectDeprecationWithIdentifier('https://github.com/doctrine/orm/issue/1234');\n\n        triggerTheCodeWithDeprecation();\n    }\n\n    public function testSomethingDeprecationFixed()\n    {\n        $this-\u003eexpectNoDeprecationWithIdentifier('https://github.com/doctrine/orm/issue/1234');\n\n        triggerTheCodeWithoutDeprecation();\n    }\n}\n```\n\n## Displaying deprecations after running a PHPUnit test suite\n\nIt is possible to integrate this library with PHPUnit to display all\ndeprecations triggered during the test suite execution.\n\n```xml\n\u003cphpunit xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n         xsi:noNamespaceSchemaLocation=\"vendor/phpunit/phpunit/phpunit.xsd\"\n         colors=\"true\"\n         bootstrap=\"vendor/autoload.php\"\n         displayDetailsOnTestsThatTriggerDeprecations=\"true\"\n         failOnDeprecation=\"true\"\n    \u003e\n    \u003c!-- one attribute to display the deprecations, the other to fail the test suite --\u003e\n\n    \u003cphp\u003e\n        \u003c!-- ensures native PHP deprecations are used --\u003e\n        \u003cserver name=\"DOCTRINE_DEPRECATIONS\" value=\"trigger\"/\u003e\n    \u003c/php\u003e\n\n    \u003c!-- ensures the @ operator in @trigger_error is ignored --\u003e\n    \u003csource ignoreSuppressionOfDeprecations=\"true\"\u003e\n        \u003cinclude\u003e\n            \u003cdirectory\u003esrc\u003c/directory\u003e\n        \u003c/include\u003e\n    \u003c/source\u003e\n\u003c/phpunit\u003e\n```\n\nNote that you can still trigger Deprecations in your code, provided you use the\n`#[WithoutErrorHandler]` attribute to disable PHPUnit's error handler for tests\nthat call it. Be wary that this will disable all error handling, meaning it\nwill mask any warnings or errors that would otherwise be caught by PHPUnit.\n\nAt the moment, it is not possible to disable deduplication with an environment\nvariable, but you can use a bootstrap file to achieve that:\n\n```php\n// tests/bootstrap.php\n\u003c?php\n\ndeclare(strict_types=1);\n\nrequire dirname(__DIR__) . '/vendor/autoload.php';\n\nuse Doctrine\\Deprecations\\Deprecation;\n\nDeprecation::withoutDeduplication();\n```\n\nThen, reference that file in your PHPUnit configuration:\n\n```xml\n\u003cphpunit …\n        bootstrap=\"tests/bootstrap.php\"\n        …\n    \u003e\n    …\n\u003c/phpunit\u003e\n```\n\n## What is a deprecation identifier?\n\nAn identifier for deprecations is just a link to any resource, most often a\nGithub Issue or Pull Request explaining the deprecation and potentially its\nalternative.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoctrine%2Fdeprecations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdoctrine%2Fdeprecations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoctrine%2Fdeprecations/lists"}