PHPackages wm/wm-package - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Framework](/categories/framework) 4. / 5. wm/wm-package ActiveLibrary[Framework](/categories/framework) wm/wm-package ============= Webmapp laravel wm-package v1.4.0(1mo ago)03.5k2[17 PRs](https://github.com/webmappsrl/wm-package/pulls)MITPHPPHP >8.1CI passing Since Feb 12Pushed 1mo ago3 watchersCompare [ Source](https://github.com/webmappsrl/wm-package)[ Packagist](https://packagist.org/packages/wm/wm-package)[ Docs](https://github.com/wm/wm-package)[ RSS](/packages/wm-wm-package/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (9)Dependencies (61)Versions (60)Used By (0) Webmapp Laravel wm-package ========================== [](#webmapp-laravel-wm-package) [![Latest Version on Packagist](https://camo.githubusercontent.com/c63e7c1f10294d9a0bb66fe6c463080d0d9704686b2d11be36ba15dd62db2f37/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f776d2f776d2d7061636b6167652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/wm/wm-package)[![GitHub Tests Action Status](https://camo.githubusercontent.com/d53f29493d6d63feb172aa394d30262f4069c77b11a8056296f5965d94c1e77d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f776d2f776d2d7061636b6167652f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/wm/wm-package/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/4a6c4dee4be09a46b8d320069aa53ce1b11fd35ffc98f4ceeca018cc9d66f6a1/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f776d2f776d2d7061636b6167652f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/wm/wm-package/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/ac4f65b8b1485e550fca38be2f228ec19baed1193f187184a893ec6ad9f5cb3f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f776d2f776d2d7061636b6167652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/wm/wm-package) This is where your description should go. Limit it to a paragraph or two. Consider adding a small example. Installation ------------ [](#installation) You can install the package via composer: ``` composer require wm/wm-package ``` You can publish and run the migrations with: ``` php artisan vendor:publish --tag="wm-package-migrations" php artisan migrate ``` You can publish the config file with : ``` php artisan vendor:publish --tag="wm-package-config" ``` Usage ----- [](#usage) You can use Services with: ServiceClass::make()->method() eg: `GeometryComputationService::make()->convertToPoint($model)` You can use Models with or without extending them: `class MyEcTrackModel extends Wm\WmPackage\Models\EcTrack {...}` You can use Nova resources extending them: `class MyEcTrackNovaResource extends Wm\WmPackage\Nova\EcTrack {...}` You can use all package APIs with related controllers, see them with `php artisan route:list` You can use all clients with dependency injection or with other instanciation methods: `app( Wm\WmPackage\Http\Clients\DemClient::class)->getTechData($geojson);` Update ------ [](#update) You can update the package via composer: ``` composer update wm/wm-package ``` or updating it as submodule Developing ---------- [](#developing) To use docker containers you need to run `docker compose up -d` and enter inside with `docker compose exec -it php bash` or directly `docker compose exec -it php composer test` (check permissions on files before run it, if you have problems use the `-u` param on exec command with the id of the user who owns project files and directories, to check your current user id you can use the command `id`). Docker has the following containers: - php - postgres - redis - elasticsearch You can use them with testbench to run a complete Laravel instance with this package (see testing section for more details). Eg, you can use tesbench to run artisan commands: `./vendor/bin/testbench migrate` We use conventional commits for commit's messages (). Create a feature/fix branch from main then ask a PR to merge it into develop branch. ### On a laravel instance [](#on-a-laravel-instance) If you need this package on full laravel instance you have to add this repository as submodule in the root path of Laravel with `git submodule add {git repo}`, then add a new composer path repository in the laravel `composer.json` file: ``` "repositories": [ { "type": "path", "url": "./wm-package" } ] ``` at last you can install the package with `compose require wm/wm-package` JWT --- [](#jwt) JWT will be installed automatically as a dependency. Users only need to configure the JWT environment variables in the `.env` file using the command `php artisan jwt:secret`. The JWT package is managed as a dependency of wm-package and does not need to be installed separately in the main application. Elasticsearch ------------- [](#elasticsearch) elasticsearch mapping and settings: config/wm-elasticsearch.php elasticsearch controller: src/Http/Controllers/Api/ElasticsearchController.php Geohub Import ------------- [](#geohub-import) This package provides an Artisan command to import data from Geohub. To ensure data integrity and correctly process all relationships, **the import process must start from an `app` entity.** The command will then import all related data in a cascading manner. The import architecture is structured around a pattern of services, jobs, and a central configuration, with an Artisan command as the entry point. ### Architecture Overview [](#architecture-overview) The main components are: 1. **CLI Command (`WmImportFromGeohubCommand`):** The entry point to initiate imports. 2. **Services (`GeohubImportService`, `EcMediaImportService`):** Handle the core business logic, data transformation, and orchestration. 3. **Jobs (e.g., `ImportAppJob`, `ImportEcTrackJob`):** Perform specific import operations for different entities in the background. 4. **Configuration (`config/wm-geohub-import.php`):** Contains mappings, database connections for Geohub, and other settings that define how the import process behaves. ### Command Usage [](#command-usage) The main command is `wm:import-from-geohub`. 1. **Import a specific application and its related data:**This is the standard way to import a complete set of data related to a specific application. ``` php artisan wm:import-from-geohub app ``` Replace `` with the ID of the application in Geohub. 2. **Import all applications and their related data:**If no model or ID is specified (or if `app` is specified without an ID), the command will import all `app` entities from Geohub, subsequently triggering the import for all their related data. ``` php artisan wm:import-from-geohub ``` Or: ``` php artisan wm:import-from-geohub app ``` ### Import Process Deep Dive [](#import-process-deep-dive) The import process is orchestrated by `GeohubImportService`. #### 1. `GeohubImportService` - The Core Orchestrator [](#1-geohubimportservice---the-core-orchestrator) This service is central to the import system and manages: - **Geohub Database Connection:** Connects to the Geohub source database using credentials and settings defined in `config/wm-geohub-import.php`. - **Orchestration:** Coordinates the import of different entities. While the primary flow starts with an `app` and cascades, the service internally might respect a specific order for fetching or processing, defined by constants like `MODEL_IMPORT_ORDER` if applicable for broad imports. ``` // Example: // protected const MODEL_IMPORT_ORDER = [ // 'app', // 'ec_poi', // // ... other models // ]; ``` - **Data Transformation:** Converts data from Geohub's format to the local application's format, often leveraging the `DataTransformer` utility. - **Relationship Management:** Ensures that associations between entities are correctly established and maintained during the import. #### 2. Data Mapping and Configuration (`config/wm-geohub-import.php`) [](#2-data-mapping-and-configuration-configwm-geohub-importphp) This crucial configuration file defines how different entities are handled. For each entity type, it specifies: - `namespace`: The local Eloquent model's namespace. - `job`: The dedicated import Job class for that entity. - `geohub_table`: The source table name in the Geohub database. - `identifier`: The field used as a unique identifier (e.g., `custom_properties->geohub_id`). - `fields`: Mapping of source fields to target fields. - `properties`: Mapping for JSON properties. - `relations`: Definitions for handling relationships with other entities. **Example: `ec_media` configuration snippet:** ``` 'ec_media' => [ 'namespace' => 'Wm\WmPackage\Models\Media', 'job' => ImportEcMediaJob::class, 'geohub_table' => 'ec_media', 'identifier' => 'custom_properties->geohub_id', 'fields' => [ // 'local_field_name' => 'geohub_field_name', ], 'properties' => [ // 'local_property_name' => 'geohub_property_name', ], 'relations' => [ // 'relation_name' => [...] ], ], ``` #### 3. Job Hierarchy and Structure [](#3-job-hierarchy-and-structure) Import jobs are organized hierarchically to share common logic: - **`BaseImportJob`:** The base class for all import jobs. It manages the general import workflow (fetch, transform, import, process dependencies) and provides common data transformation utilities. - **`BaseEcImportJob`:** Extends `BaseImportJob` specifically for "EC" entities (e.g., `EcTrack`, `EcPoi`). It handles common tasks like converting 2D geometries from Geohub to 3D and setting default values for missing geometries. - **Specific Jobs (e.g., `ImportAppJob`, `ImportEcPoiJob`, `ImportEcTrackJob`, `ImportLayerJob`, `ImportTaxonomyJob` and its derivatives):** Implement logic tailored to each entity type. Each job typically follows a structure with these key methods: - `fetchData()`: Retrieves raw data from the Geohub database for the specific entity. - `transformData()`: Converts the fetched data into the format required by the local models, often using `DataTransformer`. - `importData()`: Creates or updates the entity in the local database. - `processDependencies()`: Handles the import or linking of related entities. #### 4. Data Transformation (`DataTransformer`) [](#4-data-transformation-datatransformer) The `DataTransformer` class is a utility responsible for converting data types and structures. - **Key Features:** - Format Conversion: Transforms data between JSON, arrays, booleans, dates, etc. - Normalization: Standardizes incoming data. - Multilingual Data Handling: Converts JSON strings containing translations (e.g., `{"it":"Nome","en":"Name"}`) into associative arrays for translatable model attributes. - Implicit Validation: Manages null or empty values appropriately. - **Core Methods:** - `jsonToArray()`: Converts JSON strings to PHP arrays. - `stringToBoolean()`: Converts string representations of booleans to actual boolean values. - `stringToDate()` / `dateToString()`: Handles date conversions. - `geojsonToGeometry()`: Processes GeoJSON data into geometry objects. - **Integration:** `DataTransformer` methods are typically invoked from the mapping configuration within `config/wm-geohub-import.php` or directly within job transformation logic. **Example: Transforming a translatable `name` field:**Mapping in `wm-geohub-import.php`: ``` 'name' => [ 'field' => 'name', // Source field in Geohub data 'transformer' => [DataTransformer::class, 'jsonToArray'] ] ``` If Geohub `name` is `{"it":"Sentiero del Monte","en":"Mountain Trail"}`, it's transformed to `['it' => 'Sentiero del Monte', 'en' => 'Mountain Trail']`. #### 5. Special Case: Media Import (`ImportEcMediaJob` & `EcMediaImportService`) [](#5-special-case-media-import-importecmediajob--ecmediaimportservice) Media import (images, files) involves `ImportEcMediaJob` and potentially `EcMediaImportService` for more complex scenarios: 1. **Data Retrieval:** Fetches media metadata from Geohub. 2. **Relationship Identification:** Determines which local entity the media is associated with. 3. **Download & Upload:** Downloads the actual file from Geohub's storage and uploads it to the configured local storage (e.g., AWS S3 via Spatie Media Library). 4. **Metadata Storage:** Saves relevant metadata, including custom properties. #### 6. Queues, Batching, and Error Handling [](#6-queues-batching-and-error-handling) - **Asynchronous Processing:** All import operations are dispatched as jobs to a configurable queue (default: `geohub-import`) for background processing, which is essential for handling large datasets. - **Batching:** Jobs are often grouped into batches. Batches can be configured with failure tolerance, allowing the overall import to continue even if some individual jobs fail. - **Logging:** Comprehensive logging is implemented. Operations are logged to a dedicated channel (configurable via `wm-geohub-import.import_log_channel`, e.g., `storage/logs/wm-package-failed-jobs.log`). - **Exceptions:** Specific exceptions are used to provide detailed error messages, aiding in debugging. #### 7. Performance Considerations [](#7-performance-considerations) The system is designed to handle potentially large volumes of data: - **Queues & Jobs:** Laravel's queue system distributes the workload. - **Batching:** Efficiently processes groups of jobs. - **Horizon:** Laravel Horizon can be used to monitor and manage the queues. ### Summary of Import Flow [](#summary-of-import-flow) When an import is initiated (typically for an `app`): 1. `WmImportFromGeohubCommand` delegates to `GeohubImportService`. 2. `GeohubImportService` connects to the Geohub DB and identifies entities to import (starting with the specified `app` or all `app`s). 3. It creates and dispatches a batch of jobs (e.g., `ImportAppJob`). 4. Each job in the sequence: a. Fetches data from Geohub (`fetchData`). b. Transforms data using mappings and `DataTransformer` (`transformData`). c. Creates or updates the entity in the local database (`importData`). d. Queues further jobs for dependent entities (`processDependencies`). 5. Media imports handle file downloads/uploads separately. 6. The process is logged, and errors are managed to ensure robustness. This architecture provides a modular, robust, configurable, and scalable process for synchronizing data from Geohub. Testing ------- [](#testing) ``` composer test ``` These tools are used to test the stand alone instance of wm-package: Execute these commands to runs tests: `./vendor/bin/testbench vendor:publish --tag="wm-package-migrations"``./vendor/bin/testbench migrate`It migrates workbench tables on a postgres database. `composer test`To run tests. If an evaluation of testbench env I suggest to use the `config()` function (eg: `config('database.connections')`) with the testbench implementation of tinker `./vendor/bin/testbench tinker`, it is also useful to understand which things are loaded on the testbench env. Testbench reference: Workbench reference: Also a simple php docker container is available to run tests, you can start it using `docker compose up -d` and enter inside with `docker compose exec -it php bash` or directly `docker compose exec -it php composer test` (check permissions on files before run it, if you have problems use the `-u` param on exec command with the id of the user who owns project files and directories, to check your current user id you can use the command `id`). Pushing ------- [](#pushing) We use convetional commits () to add commits to this repo. Please create a new branch then push it and ask a pull request via github interface from your feature/fix branch to develop. Run `./vendor/bin/phpstan` before push to evaluate phpstan suggestions License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. Docs ---- [](#docs) ### Health Score 52 — FairBetter than 96% of packages Maintenance90 Actively maintained with recent releases Popularity22 Limited adoption so far Community19 Small or concentrated contributor base Maturity68 Established project with proven stability Bus Factor2 2 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~112 days Total 11 Last Release 56d ago PHP version history (3 changes)1.0PHP ^8.1 v1.2.1PHP ^8.2||^8.1 v1.2.4PHP >8.1 ### Community Maintainers ![](https://www.gravatar.com/avatar/cdf543f774c91267c506551e964a14e4011775f16ec7d08ff7ffa29f9ad6cfe7?d=identicon)[webmappsrl](/maintainers/webmappsrl) --- Top Contributors [![mbaroncini](https://avatars.githubusercontent.com/u/100847596?v=4)](https://github.com/mbaroncini "mbaroncini (756 commits)")[![gemanzo](https://avatars.githubusercontent.com/u/75580783?v=4)](https://github.com/gemanzo "gemanzo (349 commits)")[![peppedeka](https://avatars.githubusercontent.com/u/14872288?v=4)](https://github.com/peppedeka "peppedeka (293 commits)")[![peco11](https://avatars.githubusercontent.com/u/171699404?v=4)](https://github.com/peco11 "peco11 (45 commits)")[![piccioli](https://avatars.githubusercontent.com/u/681753?v=4)](https://github.com/piccioli "piccioli (38 commits)")[![FalconClaws059](https://avatars.githubusercontent.com/u/83666067?v=4)](https://github.com/FalconClaws059 "FalconClaws059 (31 commits)")[![carlacupani](https://avatars.githubusercontent.com/u/106090805?v=4)](https://github.com/carlacupani "carlacupani (20 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (19 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (14 commits)")[![pedramkat](https://avatars.githubusercontent.com/u/41744016?v=4)](https://github.com/pedramkat "pedramkat (9 commits)")[![RubensGarofalo](https://avatars.githubusercontent.com/u/122286591?v=4)](https://github.com/RubensGarofalo "RubensGarofalo (7 commits)")[![gecche](https://avatars.githubusercontent.com/u/11093763?v=4)](https://github.com/gecche "gecche (5 commits)")[![webmappsrl](https://avatars.githubusercontent.com/u/35734764?v=4)](https://github.com/webmappsrl "webmappsrl (2 commits)") --- Tags laravelwmwm-package ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/wm-wm-package/health.svg) ``` [![Health](https://phpackages.com/badges/wm-wm-package/health.svg)](https://phpackages.com/packages/wm-wm-package) ``` ### Alternatives [bagisto/bagisto Bagisto Laravel E-Commerce 26.2k161.6k7](/packages/bagisto-bagisto)[unopim/unopim UnoPim Laravel PIM 9.4k1.8k](/packages/unopim-unopim)[bytefury/crater Free & Open Source Invoice App for Individuals & Small Businesses. https://craterapp.com 8.3k4.2k](/packages/bytefury-crater)[fleetbase/core-api Core Framework and Resources for Fleetbase API 1225.0k10](/packages/fleetbase-core-api) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)