{"id":14987408,"url":"https://github.com/claudsonm/cep-promise-php","last_synced_at":"2025-10-10T12:38:01.666Z","repository":{"id":38109447,"uuid":"177436507","full_name":"claudsonm/cep-promise-php","owner":"claudsonm","description":"Busca por CEP utilizando Promises nos serviços dos Correios, ViaCEP, CepAberto e outros.","archived":false,"fork":false,"pushed_at":"2024-10-07T13:06:45.000Z","size":528,"stargazers_count":30,"open_issues_count":2,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-09-22T02:22:50.713Z","etag":null,"topics":["cep","cepaberto","codeigniter","composer","composer-package","correios","laravel","packagist","php","promise","symfony","viacep","zend-framework"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/claudsonm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2019-03-24T15:57:21.000Z","updated_at":"2025-07-25T22:30:39.000Z","dependencies_parsed_at":"2024-06-21T16:42:58.659Z","dependency_job_id":"d1e00f04-7044-4b68-8504-3317802f6b6a","html_url":"https://github.com/claudsonm/cep-promise-php","commit_stats":{"total_commits":54,"total_committers":4,"mean_commits":13.5,"dds":"0.14814814814814814","last_synced_commit":"9406b385e2ec32dbd461ddcd46846416fa70b169"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/claudsonm/cep-promise-php","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claudsonm%2Fcep-promise-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claudsonm%2Fcep-promise-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claudsonm%2Fcep-promise-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claudsonm%2Fcep-promise-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/claudsonm","download_url":"https://codeload.github.com/claudsonm/cep-promise-php/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claudsonm%2Fcep-promise-php/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279003896,"owners_count":26083641,"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","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cep","cepaberto","codeigniter","composer","composer-package","correios","laravel","packagist","php","promise","symfony","viacep","zend-framework"],"created_at":"2024-09-24T14:14:34.380Z","updated_at":"2025-10-10T12:38:01.648Z","avatar_url":"https://github.com/claudsonm.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CEP Promise PHP\n[![Run Tests](https://github.com/claudsonm/cep-promise-php/actions/workflows/run-tests.yml/badge.svg)](https://github.com/claudsonm/cep-promise-php/actions/workflows/run-tests.yml)\n[![Check \u0026 fix styling](https://github.com/claudsonm/cep-promise-php/actions/workflows/php-cs-fixer.yml/badge.svg)](https://github.com/claudsonm/cep-promise-php/actions/workflows/php-cs-fixer.yml)\n![Packagist](https://img.shields.io/packagist/dt/claudsonm/cep-promise-php)\n[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg)](#contributors)\n\nUm pacote agnóstico para PHP 7.4 e 8.0+ que efetua a busca de CEPs em diversos serviços utilizando [Promises/A+](https://promisesaplus.com/). \nInspirado no pacote [CEP Promise](https://github.com/filipedeschamps/cep-promise) \npara Node.js e web browsers.\n\n## Features\n- Realiza requests de forma concorrente, retornando sempre a resposta mais rápida;\n- Possui alta disponibilidade por utilizar diversos provedores de serviço diferentes;\n- Base de CEPs sempre atualizada, já que conecta-se com diversos serviços, dentre eles os Correios;\n- Sem limites de requisições (*rate limits*) conhecidas;\n- Feito utilizando a implementação para PHP de promises do pacote [guzzle/promises](https://github.com/guzzle/promises);\n\n## Instalação\nA maneira recomendada de instalar o pacote é via [Composer](https://getcomposer.org/download/).\nCom a ferramenta instalada, execute o comando abaixo:\n\n```bash\ncomposer require claudsonm/cep-promise-php\n```\n\nApós instalar, você precisará requerer o autoloader do Composer por meio da\ninstrução:\n\n```php\nrequire 'vendor/autoload.php';\n```\n\n## Exemplos de Uso\n\n### Exemplo 1\nBusca utilizando valores inteiros e resposta em forma de objeto.\n\n```php\n\u003c?php\n\nuse Claudsonm\\CepPromise\\CepPromise;\n\nrequire 'vendor/autoload.php';\n\n$address = CepPromise::fetch(49040610);\n\n/* \nClaudsonm\\CepPromise\\Address Object\n(\n    [city] =\u003e Aracaju\n    [district] =\u003e Inácio Barbosa\n    [state] =\u003e SE\n    [street] =\u003e Rua Universo\n    [zipCode] =\u003e 49040610\n)\n*/\n```\n\n### Exemplo 2\nBusca utilizando uma string numérica e resposta em forma de array.\n\n```php\n\u003c?php\n\nuse Claudsonm\\CepPromise\\CepPromise;\n\nrequire 'vendor/autoload.php';\n\n$address = CepPromise::fetch('78710857')-\u003etoArray();\n\n/*\n Array\n(\n    [city] =\u003e Rondonópolis\n    [district] =\u003e Vila Marinópolis\n    [state] =\u003e MT\n    [street] =\u003e Rua Pirajuí\n    [zipCode] =\u003e 78710857\n)\n*/\n```\n\n### Exemplo 3\nBusca utilizando uma string com formatação.\n\n```php\n\u003c?php\n\nuse Claudsonm\\CepPromise\\CepPromise;\n\nrequire 'vendor/autoload.php';\n\n$address = CepPromise::fetch('59067-540');\necho $address-\u003ezipCode;\necho $address-\u003estreet;\necho $address-\u003edistrict;\necho $address-\u003ecity;\necho $address-\u003estate;\n\n/*\n'59067540'\n'Rua Figueira'\n'Pitimbu'\n'Natal'\n'RN'\n*/\n```\n\n### Exemplo 4\nCaptura e tratamento de erros.\n\n```php\n\u003c?php\n\nuse Claudsonm\\CepPromise\\CepPromise;\nuse Claudsonm\\CepPromise\\Exceptions\\CepPromiseException;\n\nrequire 'vendor/autoload.php';\n\ntry {\n    $response = CepPromise::fetch('99999999');\n} catch (CepPromiseException $e) {\n    $response = $e-\u003etoArray();\n}\n\n/*\nArray\n(\n    [message] =\u003e Todos os serviços de CEP retornaram erro.\n    [code] =\u003e 2\n    [errors] =\u003e Array\n        (\n            [0] =\u003e Array\n                (\n                    [provider] =\u003e via_cep\n                    [message] =\u003e CEP não encontrado na base do ViaCEP.\n                )\n\n            [1] =\u003e Array\n                (\n                    [provider] =\u003e cep_aberto\n                    [message] =\u003e Erro ao se conectar com o serviço CEP Aberto.\n                )\n\n            [2] =\u003e Array\n                (\n                    [provider] =\u003e correios\n                    [message] =\u003e CEP INVÁLIDO\n                )\n\n        )\n\n)\n*/\n```\n\n## Contribuidores\n\nUm muito obrigado a todos os serumaninhos que contribuiram com este repositório:\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore --\u003e\n\u003ctable\u003e\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/claudsonm\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/4139808?v=4\" width=\"100px;\" alt=\"Claudson Martins\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eClaudson Martins\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#projectManagement-claudsonm\" title=\"Project Management\"\u003e📆\u003c/a\u003e \u003ca href=\"#maintenance-claudsonm\" title=\"Maintenance\"\u003e🚧\u003c/a\u003e \u003ca href=\"https://github.com/claudsonm/cep-promise-php/commits?author=claudsonm\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/claudsonm/cep-promise-php/commits?author=claudsonm\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"#example-claudsonm\" title=\"Examples\"\u003e💡\u003c/a\u003e \u003ca href=\"#business-claudsonm\" title=\"Business development\"\u003e💼\u003c/a\u003e \u003ca href=\"#tutorial-claudsonm\" title=\"Tutorials\"\u003e✅\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nEste projeto segue a especificação do [all-contributors](https://github.com/all-contributors/all-contributors). Contribuições de qualquer natureza são bem vindas!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaudsonm%2Fcep-promise-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclaudsonm%2Fcep-promise-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaudsonm%2Fcep-promise-php/lists"}