{"id":37233473,"url":"https://github.com/plin-code/laravel-istat-foreign-countries","last_synced_at":"2026-01-15T03:54:17.246Z","repository":{"id":323527024,"uuid":"1093459347","full_name":"plin-code/laravel-istat-foreign-countries","owner":"plin-code","description":"🇮🇹 Import and manage ISTAT foreign countries (continents, areas, states, and territories) with Eloquent models, ISO/ISTAT codes, and an Artisan import command.","archived":false,"fork":false,"pushed_at":"2025-11-26T16:41:13.000Z","size":46,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-29T13:49:37.994Z","etag":null,"topics":["country","geography","hacktoberfest","istat","laravel"],"latest_commit_sha":null,"homepage":"","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/plin-code.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"PlinCode"}},"created_at":"2025-11-10T12:01:08.000Z","updated_at":"2025-11-26T16:41:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/plin-code/laravel-istat-foreign-countries","commit_stats":null,"previous_names":["plin-code/laravel-istat-foreign-countries"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/plin-code/laravel-istat-foreign-countries","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plin-code%2Flaravel-istat-foreign-countries","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plin-code%2Flaravel-istat-foreign-countries/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plin-code%2Flaravel-istat-foreign-countries/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plin-code%2Flaravel-istat-foreign-countries/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plin-code","download_url":"https://codeload.github.com/plin-code/laravel-istat-foreign-countries/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plin-code%2Flaravel-istat-foreign-countries/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28419272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T10:47:48.104Z","status":"ssl_error","status_checked_at":"2026-01-14T10:46:19.031Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["country","geography","hacktoberfest","istat","laravel"],"created_at":"2026-01-15T03:54:16.631Z","updated_at":"2026-01-15T03:54:17.223Z","avatar_url":"https://github.com/plin-code.png","language":"PHP","funding_links":["https://github.com/sponsors/PlinCode"],"categories":[],"sub_categories":[],"readme":"# Laravel ISTAT Foreign Countries\n\nA Laravel package for importing and managing foreign countries data from ISTAT (Italian National Institute of Statistics).\n\n## Features\n\n- 🌍 Import continents, geographical areas, and foreign countries from ISTAT\n- 🔗 Eloquent models with hierarchical relationships\n- ⚡ Artisan command for easy data import\n- 🔧 Fully configurable via configuration file\n- 🆔 UUID primary keys and soft deletes support\n- 🏷️ Multiple coding standards support (ISTAT, ISO, MIN, AT)\n\n## Requirements\n\n- PHP 8.3+\n- Laravel 12.0+\n- league/csv 9.0+\n- guzzlehttp/guzzle 7.0+\n\n## Installation\n\n```bash\ncomposer require plin-code/laravel-istat-foreign-countries\n```\n\n## Quick Start\n\n1. **Install the package:**\n```bash\ncomposer require plin-code/laravel-istat-foreign-countries\n```\n\n2. **Publish the configuration:**\n```bash\nphp artisan vendor:publish --provider=\"PlinCode\\IstatForeignCountries\\IstatForeignCountriesServiceProvider\"\n```\n\n3. **Run migrations:**\n```bash\nphp artisan migrate\n```\n\n4. **Import the data:**\n```bash\nphp artisan foreign-countries:import\n```\n\nThat's it! You now have all foreign countries data in your database.\n\n## Configuration\n\nPublish the configuration file:\n\n```bash\nphp artisan vendor:publish --provider=\"PlinCode\\IstatForeignCountries\\IstatForeignCountriesServiceProvider\"\n```\n\n## Usage\n\n### Data Import\n\nTo import all foreign countries data from ISTAT:\n\n```bash\nphp artisan foreign-countries:import\n```\n\n### Models\n\nThe package provides three Eloquent models:\n\n#### Continent\n```php\nuse PlinCode\\IstatForeignCountries\\Models\\ForeignCountries\\Continent;\n\n$continent = Continent::where('name', 'Europa')-\u003efirst();\n$areas = $continent-\u003eareas;\n$countries = $continent-\u003ecountries;\n```\n\n#### Area\n```php\nuse PlinCode\\IstatForeignCountries\\Models\\ForeignCountries\\Area;\n\n$area = Area::where('name', 'Unione europea')-\u003efirst();\n$countries = $area-\u003ecountries;\n$continent = $area-\u003econtinent;\n```\n\n#### Country\n```php\nuse PlinCode\\IstatForeignCountries\\Models\\ForeignCountries\\Country;\n\n// Find by ISO alpha2\n$country = Country::where('iso_alpha2', 'FR')-\u003efirst();\n\n// Find by ISO alpha3\n$country = Country::where('iso_alpha3', 'FRA')-\u003efirst();\n\n// Find by ISTAT code\n$country = Country::where('istat_code', '215')-\u003efirst();\n\n// Access relationships\n$continent = $country-\u003econtinent;\n$area = $country-\u003earea;\n\n// Check type\nif ($country-\u003eisState()) {\n    echo \"This is a state\";\n}\n\nif ($country-\u003eisTerritory()) {\n    echo \"This is a territory\";\n    $parent = $country-\u003eparentCountry;\n}\n\n// Get territories of a country\n$france = Country::where('iso_alpha2', 'FR')-\u003efirst();\n$territories = $france-\u003eterritories;\n```\n\n### Facade Usage\n\n```php\nuse PlinCode\\IstatForeignCountries\\Facades\\IstatForeignCountries;\n\n// Import data programmatically\n$count = IstatForeignCountries::import();\n```\n\n### Available Codes\n\nEach country includes multiple international coding standards:\n\n- **ISTAT Code**: Italian statistical code\n- **ISO Alpha-2**: Two-letter country code (e.g., \"FR\")\n- **ISO Alpha-3**: Three-letter country code (e.g., \"FRA\")\n- **AT Code**: Italian territorial code\n\n## Database Structure\n\n### Continents\n- `id` (UUID, primary key)\n- `name` (string)\n- `istat_code` (string, unique)\n- `created_at`, `updated_at`, `deleted_at`\n\n### Areas\n- `id` (UUID, primary key)\n- `continent_id` (UUID, foreign key)\n- `name` (string)\n- `istat_code` (string, unique)\n- `created_at`, `updated_at`, `deleted_at`\n\n### Countries\n- `id` (UUID, primary key)\n- `continent_id` (UUID, foreign key)\n- `area_id` (UUID, foreign key)\n- `parent_country_id` (UUID, foreign key, nullable)\n- `type` (string: 'S' for State, 'T' for Territory)\n- `name` (string: Italian name)\n- `istat_code` (string, unique)\n- `iso_alpha2` (string, 2 chars)\n- `iso_alpha3` (string, 3 chars)\n- `at_code` (string)\n- `created_at`, `updated_at`, `deleted_at`\n\n## Relationships\n\n- `Continent` → `hasMany` → `Area`\n- `Continent` → `hasMany` → `Country`\n- `Area` → `belongsTo` → `Continent`\n- `Area` → `hasMany` → `Country`\n- `Country` → `belongsTo` → `Continent`\n- `Country` → `belongsTo` → `Area`\n- `Country` → `belongsTo` → `Country` (parent country, for territories)\n- `Country` → `hasMany` → `Country` (territories)\n\n## Configuration\n\nThe `config/istat-foreign-countries.php` file allows you to customize:\n\n- **Database connection**: Specify a custom database connection\n- **Table names**: Customize the database table names\n- **Model classes**: Use your own model classes by extending the base ones\n- **CSV URL**: Change the ISTAT data source URL\n- **Temporary file name**: Customize the cache file name\n\n### Example Configuration\n```php\nreturn [\n    'database_connection' =\u003e null,\n\n    'tables' =\u003e [\n        'continents' =\u003e 'continents',\n        'areas' =\u003e 'areas',\n        'countries' =\u003e 'countries',\n    ],\n\n    'models' =\u003e [\n        'continent' =\u003e \\App\\Models\\Continent::class,\n        'area' =\u003e \\App\\Models\\Area::class,\n        'country' =\u003e \\App\\Models\\Country::class,\n    ],\n\n    'import' =\u003e [\n        'csv_url' =\u003e 'https://www.istat.it/storage/codici-unita-amministrative/Elenco-codici-e-denominazioni-unita-territoriali-estere.csv',\n        'temp_filename' =\u003e 'istat_foreign_countries.csv',\n    ],\n];\n```\n\n## Testing\n\nRun the test suite:\n\n```bash\ncomposer test\n```\n\nThe package includes:\n- ✅ Unit tests for models and relationships\n- ✅ Feature tests for the import service\n- ✅ Mocked HTTP requests (no external dependencies)\n- ✅ PHPStan static analysis (Level 5)\n- ✅ Pest PHP testing framework\n- ✅ Architecture tests\n\n### Run Static Analysis\n```bash\ncomposer analyse\n```\n\n### Code Style Formatting\n```bash\ncomposer format\n```\n\n## Contributing\n\n1. Fork the project\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## Credits\n\nData source: [ISTAT - Italian National Institute of Statistics](https://www.istat.it/)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplin-code%2Flaravel-istat-foreign-countries","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplin-code%2Flaravel-istat-foreign-countries","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplin-code%2Flaravel-istat-foreign-countries/lists"}