{"id":41824644,"url":"https://github.com/fndmiranda/simple-address","last_synced_at":"2026-01-25T08:07:06.453Z","repository":{"id":62506076,"uuid":"189122049","full_name":"fndmiranda/simple-address","owner":"fndmiranda","description":"Management, geocoding and address search by postcode in multiple Api`s","archived":false,"fork":false,"pushed_at":"2020-07-14T15:00:18.000Z","size":31,"stargazers_count":76,"open_issues_count":0,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-04T13:02:41.767Z","etag":null,"topics":["address","addresses","cep","correios","geocode","postcode","zipcode"],"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/fndmiranda.png","metadata":{"files":{"readme":"README-pt-BR.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-05-29T00:26:19.000Z","updated_at":"2024-11-16T14:09:05.000Z","dependencies_parsed_at":"2022-11-02T12:31:00.657Z","dependency_job_id":null,"html_url":"https://github.com/fndmiranda/simple-address","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/fndmiranda/simple-address","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fndmiranda%2Fsimple-address","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fndmiranda%2Fsimple-address/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fndmiranda%2Fsimple-address/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fndmiranda%2Fsimple-address/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fndmiranda","download_url":"https://codeload.github.com/fndmiranda/simple-address/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fndmiranda%2Fsimple-address/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28748573,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T07:58:02.558Z","status":"ssl_error","status_checked_at":"2026-01-25T07:57:57.153Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["address","addresses","cep","correios","geocode","postcode","zipcode"],"created_at":"2026-01-25T08:07:05.923Z","updated_at":"2026-01-25T08:07:06.440Z","avatar_url":"https://github.com/fndmiranda.png","language":"PHP","readme":"# Art of README\n\n*Este artigo foi traduzido do [Inglês](README.md) e traduzido para [Português](README-pt-BR.md).*\n\n## Endereço simples para Laravel\n\nEste pacote simplifica a busca de endereços por CEP em Api's e o gerenciamento de endereços no banco de dados,\nvocê também pode criar seus próprios adaptadores para consultas em uma Api.\n\n### Instalação\n\n```\ncomposer require fndmiranda/simple-address\n```\n\n### Uso\n\nPublique o arquivo de configuração do pacote com o comando `vendor:publish` Artisan:\n\n```terminal\nphp artisan vendor:publish --tag=simple-address-config\n```\n\nO arquivo de configuração publicado `address.php` será colocado no diretório `config`.\n\n## Api`s para pesquisa\n\nA lista de Api disponível está localizada no seu arquivo `config/address.php` no `apis` e você pode remover ou \nadicionar novos adaptadores da seguinte maneira:\n\n```php\n'apis' =\u003e [\n    Fndmiranda\\SimpleAddress\\Adapters\\ViaCepAdapter::class,\n    Fndmiranda\\SimpleAddress\\Adapters\\PostmonAdapter::class,\n    Fndmiranda\\SimpleAddress\\Adapters\\WidenetAdapter::class,\n],\n```\n\nSe você alterar `force_priority` em `config/address.php` para `true`, a ordem de busca sempre estará de \nacordo com a lista de adaptadores em `apis`, por padrão, esse valor é `false` para que a ordem seja aleatória.\n\nCom o método `search` da facade do `Address`, o pacote executará um loop nas apis até encontrar o endereço \ncom o CEP solicitado da seguinte forma:\n\n```php\n$address = Address::search(38017170);\n```\n\n## Geocodificação\n\nVocê pode usar os dados retornados pelo método `search` para obter a `latitude` e a `longitude` do endereço com o\nmétodo `geocoding` da facade `Address` da seguinte forma:\n\n```php\n$address = Address::search(38017170);\n\n$geocode = Address::geocoding($address);\n```\n\nObservação, para usar o recurso `geocoding` você precisa fornecer a `key` da API do Google Maps, \nadicione a entrada `ADDRESS_GOOGLE_MAPS_KEY` no seu arquivo `.env` da seguinte maneira:\n\n```env\nADDRESS_GOOGLE_MAPS_KEY=YourMapsKey\n```\n\n## Banco de dados\n\nEste pacote vem com uma estrutura de banco de dados completa para armazenar os endereços pesquisados.\n\nObserve que uma tabela para polimorfismo será criada e que deve ser criada com o tipo de coluna igual ao que fará \nrelação com suas tabelas, para isso você deve definir o `column_type` no arquivo `config/address.php`\nas opções são `integer`, `bigInteger` e `uuid`, então crie as tabelas com o comando `migrate` Artisan:\n\n```terminal\nphp artisan migrate\n```\n\n### Personalização das migrações\n\nSe você não for usar as migrações padrão do SimpleAddress, você deve chamar o método `Address::ignoreMigrations` no \nmétodo `register` do seu `AppServiceProvider`.\nE então exportar as migrações padrão usando o comando `vendor:publish` Artisan:\n\n```terminal\nphp artisan vendor:publish --tag=simple-address-migrations\n```\n\nSe você não deseja gerenciar os endereços no banco de dados e apenas deseja consultar nas Api's,\nmude o `manager_address` no arquivo `config/address.php` para `false`.\n\n### Salvando no banco de dados\n\nExemplo de integração do modelo de fornecedor com polimorfismo de endereço.\n\n```php\n\u003c?php\n\nnamespace App\\Supplier;\n\nuse Fndmiranda\\SimpleAddress\\Entities\\Address;\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Fndmiranda\\SimpleAddress\\Pivot\\AddressPivot;\n\nclass Supplier extends Model\n{\n    /**\n     * The attributes that are mass assignable.\n     *\n     * @var array\n     */\n    protected $fillable = [\n        'name', 'email', 'document', 'is_active',\n    ];\n\n    /**\n     * Get all of the addresses for the supplier.\n     */\n    public function addresses()\n    {\n        return $this-\u003emorphToMany(Address::class, 'addressable', 'address_addressables')\n            -\u003ewithPivot(['number', 'complement', 'lat', 'lng', 'type'])\n            -\u003eusing(AddressPivot::class)\n            -\u003ewithTimestamps();\n    }\n}\n```\n\nVocê pode então salvar o endereço para um fornecedor usando os métodos `search` e `geocoding` da facade `Address`\ncomo no exemplo a seguir:\n\n```php\n// Encontre um fornecedor\n$supplier = \\App\\Supplier::find(1);\n\n// Pesquise um endereço por código postal\n$address = Address::search(38017170);\n\n// Obter geocódigo do endereço\n$geocode = Address::geocoding($address);\n\n// Salvar um endereço para o fornecedor\n$attributes = array_merge(['number' =\u003e 16, 'complement' =\u003e 'House'], $geocode);\n$supplier-\u003eaddresses()-\u003esave($address, $attributes);\n\n// Ou sem geocódigo\n$supplier-\u003eaddresses()-\u003esave($address, ['number' =\u003e 16, 'complement' =\u003e 'House']);\n\n// Para atualizar um endereço de fornecedor\n$supplier-\u003eaddresses()-\u003efirst()-\u003epivot-\u003eupdate(['number' =\u003e 25, 'complement' =\u003e 'Store 10']);\n```\n\n### Ou no seu controlador\n\n```php\n\u003c?php\n\nnamespace App\\Http\\Controllers;\n\nuse Illuminate\\Http\\Response;\nuse App\\Supplier;\nuse App\\Http\\Resources\\SupplierResource;\nuse App\\Repositories\\SupplierRepository;\nuse Fndmiranda\\SimpleAddress\\Facades\\Address;\nuse Fndmiranda\\SimpleAddress\\Repositories\\AddressRepository;\n\nclass SupplierController extends Controller\n{\n    /**\n     * The supplier repository instance.\n     *\n     * @var SupplierRepository\n     */\n    protected $supplierRepository;\n    \n    /**\n     * The address repository instance.\n     *\n     * @var AddressRepository\n     */\n    protected $addressRepository;\n    \n    /**\n     * Create a new controller instance.\n     *\n     * @return void\n     */\n    public function __construct(SupplierRepository $supplierRepository, AddressRepository $addressRepository)\n    {\n        $this-\u003esupplierRepository = $supplierRepository;\n        $this-\u003eaddressRepository = $addressRepository;\n    }\n    \n    /**\n     * Store a newly created resource in storage.\n     *\n     * @param SupplierRequest $request\n     * @return Response\n     */\n    public function store(SupplierRequest $request)\n    {\n        $attributes = $request-\u003eall();\n        \n        $entity = $this-\u003eaddressRepository-\u003ecreate($attributes);\n        \n        if (!empty($attributes['address'])) {\n            if (!empty(config('address.google_maps_key'))) {\n                $address = $this-\u003eaddressRepository-\u003efind($attributes['address']['address_id']);\n                $geocode = Address::geocoding($address, $attributes['address']);\n                if (!empty($geocode)) {\n                    array_merge($attributes['address'], $geocode);\n                }\n            }\n\n            $entity-\u003eaddresses()-\u003esync([$attributes['address']['address_id'] =\u003e $attributes['address']]);\n        }\n        \n        $data = SupplierResource::make($entity);\n        return response()-\u003ejson(['data' =\u003e $data], Response::HTTP_CREATED);\n    }\n\n    /**\n     * Update the specified resource in storage.\n     *\n     * @param SupplierRequest $request\n     * @param string $id\n     * @return AccountResource\n     */\n    public function update(SupplierRequest $request, $id)\n    {\n        $attributes = $request-\u003eall();\n        \n        $entity = $this-\u003esupplierRepository-\u003efind($id);\n        \n        if (!empty($attributes['address'])) {\n            if (!empty(config('address.google_maps_key'))) {\n                $address = $this-\u003eaddressRepository-\u003efind($attributes['address']['address_id']);\n                $geocode = Address::geocoding($address, $attributes['address']);\n                if (!empty($geocode)) {\n                    array_merge($attributes['address'], $geocode);\n                }\n            }\n\n            $entity-\u003eaddresses()-\u003esync([$attributes['address']['address_id'] =\u003e $attributes['address']]);\n        }\n\n        $entity-\u003eupdate($attributes);\n        \n        return SupplierResource::make($entity);\n    }\n}\n```\n\nExemplo do corpo da solicitação\n\n```json\n{\n  \"name\": \"Name of supplier\",\n  \"email\": \"email@domain.com\",\n  \"document\": \"11111111111\",\n  \"is_active\": true,\n  \"address\": {\n  \t\"address_id\": \"0fdecea5-9f99-47ea-87a9-3dc191839008\",\n  \t\"number\": 16,\n  \t\"complement\": \"House\"\n  }\n}\n```\n\n## Criando seu adaptador customizado\n\nVocê pode criar seu próprio adaptador personalizado para consultar uma API que não está na lista.\n\nVocê pode gerar um adaptador do comando `simple-address:make` Artisan:\n\n```terminal\nphp artisan simple-address:make YourApiAdapter\n```\n\nEste comando gerará um adaptador por padrão em `app/SimpleAddress/Adapters/YourApiAdapter.php`.\n\nO arquivo irá conter os métodos `search` e `prepare` vazios, para que você possa adaptá-los seguindo o arquivo\nde exemplo a seguir:\n\n```php\n\u003c?php\n\nnamespace App\\SimpleAddress\\Adapters;\n\nuse Fndmiranda\\SimpleAddress\\Contracts\\AdapterContract;\n\nclass YourApiAdapter implements AdapterContract\n{\n    /**\n     * Search external address by postcode.\n     *\n     * @param $postcode\n     * @return array|bool\n     * @throws \\GuzzleHttp\\Exception\\GuzzleException\n     */\n    public function search($postcode)\n    {\n        $client = new \\GuzzleHttp\\Client();\n        $request = new \\GuzzleHttp\\Psr7\\Request('GET', 'https://api.postmon.com.br/v1/cep/'.$postcode.'?format=json');\n        $response = $client-\u003esend($request);\n\n        if ($response-\u003egetStatusCode() != 200) {\n            return false;\n        }\n\n        $data = json_decode((string) $response-\u003egetBody(), true);\n\n        return $this-\u003eprepare($data);\n    }\n\n    /**\n     * Prepare address data.\n     *\n     * @param $data\n     * @return array\n     */\n    public function prepare($data)\n    {\n        return [\n            'postcode' =\u003e $data['cep'],\n            'address' =\u003e $data['logradouro'],\n            'neighborhood' =\u003e $data['bairro'],\n            'city' =\u003e $data['cidade'],\n            'state' =\u003e $data['estado'],\n        ];\n    }\n}\n```\n\nAdicione seu adaptador à lista `apis` no arquivo `config/address.php` da seguinte forma:\n\n```php\n'apis' =\u003e [\n    Fndmiranda\\SimpleAddress\\Adapters\\ViaCepAdapter::class,\n    Fndmiranda\\SimpleAddress\\Adapters\\PostmonAdapter::class,\n    Fndmiranda\\SimpleAddress\\Adapters\\WidenetAdapter::class,\n    App\\SimpleAddress\\Adapters\\YourApiAdapter::class, // Seu adaptador de Api personalizado\n],\n```\n\nSe você criar um novo adaptador para uma Api, eu agradeceria se você abrir um pull request adicionando seu adaptador e o mapeando\nna lista `apis` em `config/address.php` do pacote.\n\n### Método search\n\nO método `search` envia uma request para um endpoint para consultar um `postcode` e usa o método `prepare` para transformar os\ndados obtidos em um array padrão e os retorna ou retorna `false` se o `postcode` não for encontrado ou se a API \nnão estiver respondendo para que ele consulte automaticamente a próxima api `adapter` até encontrar o endereço pelo CEP fornecido.\n\n### Método prepare\n\nO método `prepare` deve transformar os dados retornados por uma API em um `array` padrão com as\nchaves `postcode`, `address`, `neighborhood`, `city` e `state`.\n\n## Segurança\n\nSe você descobrir algum problema relacionado à segurança, envie um e-mail para fndmiranda@gmail.com em vez de usar o \nrastreador de problemas.\n\n## Licença\n\nA licença MIT (MIT). Por favor, veja o [Arquivo de licença](LICENSE.md) para mais informações.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffndmiranda%2Fsimple-address","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffndmiranda%2Fsimple-address","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffndmiranda%2Fsimple-address/lists"}