{"id":22448172,"url":"https://github.com/monamoxie/vocab-mapper","last_synced_at":"2026-03-04T21:02:48.180Z","repository":{"id":240971358,"uuid":"803958985","full_name":"Monamoxie/vocab-mapper","owner":"Monamoxie","description":"Laravel package for both multi-tenant and single tenant architectures. Grant tenants the unique ability to map vocab of your core systems to match their preferred terminology and contextual usage.","archived":false,"fork":false,"pushed_at":"2025-03-11T18:15:57.000Z","size":65,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-11-27T15:29:42.798Z","etag":null,"topics":["laravel","multitenant-architecure","php8","phpunit","tenancy"],"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/Monamoxie.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":"2024-05-21T17:29:10.000Z","updated_at":"2025-03-11T18:15:58.000Z","dependencies_parsed_at":"2024-12-06T04:24:07.103Z","dependency_job_id":"811db28f-e3c4-4cfe-82b0-6ccfd084a421","html_url":"https://github.com/Monamoxie/vocab-mapper","commit_stats":null,"previous_names":["monamoxie/vocab-mapper"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/Monamoxie/vocab-mapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Monamoxie%2Fvocab-mapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Monamoxie%2Fvocab-mapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Monamoxie%2Fvocab-mapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Monamoxie%2Fvocab-mapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Monamoxie","download_url":"https://codeload.github.com/Monamoxie/vocab-mapper/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Monamoxie%2Fvocab-mapper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30092875,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T20:42:30.420Z","status":"ssl_error","status_checked_at":"2026-03-04T20:42:30.057Z","response_time":59,"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":["laravel","multitenant-architecure","php8","phpunit","tenancy"],"created_at":"2024-12-06T04:21:32.136Z","updated_at":"2026-03-04T21:02:43.172Z","avatar_url":"https://github.com/Monamoxie.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"files/img/logo-w.png\"\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg alt=\"Github Actions\" src=\"https://img.shields.io/badge/Architecture-Multi_Tenancy-limegreen?style=plastic\"\u003e\n\u003ca href=\"https://codecov.io/gh/Monamoxie/vocab-mapper\" \u003e \n \u003cimg src=\"https://codecov.io/gh/Monamoxie/vocab-mapper/branch/master/graph/badge.svg\"/\u003e \n \u003c/a\u003e\n\u003ca href=\"https://github.com/Monamoxie/vocab-mapper/actions/workflows/build.yml\" _target=\"blank\"\u003e\u003cimg alt=\"Github Actions\" src=\"https://github.com/Monamoxie/vocab-mapper/actions/workflows/build.yml/badge.svg?branch=master\u0026event=push\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/monamoxie/vocab-mapper\"\u003e\u003cimg src=\"https://poser.pugx.org/monamoxie/vocab-mapper/v/stable\" alt=\"Latest Stable Version\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# VOCAB MAPPER\n\nA Laravel package for both multi-tenant and single tenant architectures.\n\nVocab Mapper provides your tenants or users a personalized experience, by defining mappings between standard terminology (The Default Vocab) and user-preferred terminology (The Custom Vocab), especially when both terminologies are referring to the same core concept.\n\n## INSTALLATION\n\n```\ncomposer require monamoxie/vocab-mapper\n```\n\n## VENDOR PUBLISHING\n\nVocab Mapper includes some default configurations out of the box, but it's recommended you publish and customize these settings to suit your needs.\n\n#### PUBLISHING THE CONFIG\n\n```\nphp artisan vendor:publish --tag=vocab-mapper-config\n```\n\n#### EXPLORING THE VOCAB CONFIG\n\n###### MIGRATION SUB DIR\n\n```\nmigration_sub_dir =\u003e null\n```\n\nThis is the subdirectory where Vocab Mapper's migration files will be published. The default value is null, suitable for most single-tenant applications.\n\nFor multi-tenant systems needing a different subdirectory for tenant-specific migrations, you can simply set the subdirectory value here. For example, the stancl/tenancy multi-tenant package requires tenant migrations be kept in `database/migrations/tenant`.\n\nIf that is the case, then you should set the value of `migration_sub_dir =\u003e '/tenant'`\n\n###### ENTITY MODEL\n\nAn entity in your application is a unique tenant or user who whiches to use a custom vocabulary for a core concept, different from the standard term.\n\n###### Single-tenant systems\n\nIn single-tenant systems, this is typically the model class representing your users. For example, `\\App\\Models\\User::class`, or whichever model namespace manages and identifies your users.\n\n| key            | type           | Default Value             |\n| -------------- | -------------- | ------------------------- |\n| `entity_model` | `string,array` | `\\App\\Models\\User::class` |\n\n###### Multi-tenant systems\n\nIn multi-tenant systems, this is typically the model class representing the tenant. For example, `\\App\\Models\\Tenant::class`, or whichever model namespace manages and identifies your tenants.\n\n| key           | type           | Recommended                 |\n| ------------- | -------------- | --------------------------- |\n| `user_entity` | `string,array` | `\\App\\Models\\Tenant::class` |\n\nPlease refer to the section on [BREAK DOWN OF TERMS](#break-down-of-terms) for a more information on this.\n\n###### ENTITY HAS UUID\n\nEnable this option if the entity model utilizes a UUID as its primary key.\n\n| key                    | type      | Default Value |\n| ---------------------- | --------- | ------------- |\n| `user_entity_has_uuid` | `boolean` | `false`       |\n\n#### PUBLISHING THE MIGRATION\n\n```\nphp artisan vendor:publish --tag=vocab-mapper-migration\n```\n\nThis action will publish the migration files based on the provided configuration in `migration_sub_dir`. If no specific path is set, the files will be published to Laravel's default migration directory.\n\n## MIGRATION\n\nRun the artisan command responsible for handling your Database migrations.\n\n###### Single-tenant systems\n\n```\nphp artisan migrate\n```\n\n###### Multi-tenant systems\n\nThe command to execute depends on your setup or package configuration. For example, projects utilizing the stancl/tenancy package would execute:\n\n```\nphp artisan tenants:migrate\n```\n\n## MAKING YOUR ELOQUENT MODELS VOCABLE\n\nA vocab is a name, identity or a domain driven terminology used by default across your application. In an educational project, it could be the word `SUBJECTS` for storing all the subjects taught in a school. In an automotive project, it could be the word `VEHICLES` for identifying all vehicles available in your system.\n\nTo make any of your models `VOCABLE`, (which is the ability to maintain and be represented in a different term across multiple tenants or users), you should include the `HasVocab` trait to the model\n\n```\n\u003c?php\n\nnamespace App\\Models;\n\nuse Monamoxie\\VocabMapper\\Traits\\HasVocab;\nuse Illuminate\\Database\\Eloquent\\Model;\n\nclass MyModel extends Model\n{\n  use HasVocab;\n}\n```\n\nThat's all.\n\nWith this, this model, `MyModel`, should now be ready to accept and maintain different identites across each of your tenants or users.\n\n#### CREATING A DEFAULT VOCAB\n\nFrom any part of your application, you can call\n\n```\n\u003c?php\n\nuse App\\Models\\MyModel;\n\n(new MyModel)-\u003ecreateVocab(name: 'Vocab Name');\n```\n\nThe `name` argument is optional. If not provided, the default vocab (term, identity) for this model would the table name.\n\n#### MAPPING A VOCAB TO AN ENTITY\n\nFrom any part of your application, you can call\n\n```\n\u003c?php\n\nuse App\\Models\\MyModel;\n\n(new MyModel)-\u003emapVocabTo($entity, $customName);\n```\n\nwhere:\n\n```\n$entity = An instance of your entity model, as defined in the config, entity_model\n```\n\n```\n$customName = The custom terminology set or choosen by this $entity.\n```\n\nThis entity could be the currently logged in tenant or currently logged in user. It doesn't matter.\n\nYou must ensure the instance of this entity matches what you defined in the config, `entity_model`.\n\nIf there is a mis-match between the $entity instance and whatever was set in the config, `entity_model`, this will thrown an exception of type:\n\n```\nMonamoxie\\VocabMapper\\Exceptions\\InvalidEntityModelException\n```\n\n##### THE DUALITY OF mapVocabTo\n\nIf you attempt to map a vocab to an entity and Vocab Mapper detects that the vocab doesn't exist, it will silently create a new vocab and proceed with the mapping.\n\n#### GETTING THE VOCAB MAPPED TO AN ENTITY\n\nFrom any part of your application, you can call\n\n```\n\u003c?php\n\nuse App\\Models\\MyModel;\n\n(new MyModel)-\u003egetVocabFor($entity);\n```\n\nwhere:\n\n```\n$entity is an instance of your entity model, as defined in the config, entity_model\n```\n\n#### THE VOCAB COLLECTOR\n\nAlternatively, you could also take advantage of the Vocab Collector for getting the vocab mapped to a user:\n\n```\n\u003c?php\n\nuse App\\Models\\MyModel;\nuse Monamoxie\\VocabMapper\\Facades\\VocabCollector;\n\nVocabCollector::getFor($entity, MyModel::class)\n```\n\nwhere:\n\n```\n$entity is an instance of your entity model.\n\nThis could be an instance of \\App\\Models\\Tenant, or \\App\\Models\\User or whatever. As long as it the namespace matches what you defined in the `user_model` config\n```\n\n#### THE DIFFERENCE BETWEEN getVocabFor and VocabCollector::getFor\n\n`(new MyModel)-\u003egetVocabFor($entity)` will return an eloquent model, which is an instance of `Monamoxie\\VocabMapper\\VocabMapper`\n\nYou may want to use this to inspect the model or for any eloquent operations.\n\nAlternatively, `VocabCollector::getFor` returns an instance of `Monamoxie\\VocabMapper\\Data\\VocabResponse`, which is ideal for displaying this data in the client-facing part of your application.\n\nThe `VocabResponse` provides the custom vocabulary defined by the entity, including its singular and plural forms.\n\nFor instance, you could have a setup like this in your controller:\n\n```\n\u003c?php\n\nuse App\\Models\\MyModel;\nuse Monamoxie\\VocabMapper\\Facades\\VocabCollector;\n\npublic function index()\n{\n    $entity = Tenant::where('id', auth()-\u003euser()-\u003eid)-\u003efirst();\n\n    return view('academy.foo.bar', [\n        'vocab' =\u003e VocabCollector::getFor($entity, MyModel::class),\n        'data' =\u003e 'some random data',\n        'data2' =\u003e 'some other random data'\n    ]);\n}\n```\n\nAnd if it's an API driven setup, you could also have something like this. It doesn't matter.\n\n```\n\u003c?php\n\nuse Illuminate\\Support\\Facades\\Response;\nuse App\\Models\\MyModel;\nuse Monamoxie\\VocabMapper\\Facades\\VocabCollector;\n\npublic function get()\n{\n    $entity = Tenant::where('id', auth()-\u003euser()-\u003eid)-\u003efirst();\n\n    return Response::json([\n      'message' =\u003e '',\n      'data' =\u003e 'SOME DATA',\n      'vocab' =\u003e VocabCollector::getFor($entity, MyModel::class),\n    ], 200);\n}\n```\n\nYou are also not limited to working with just the instance of `Monamoxie\\VocabMapper\\Data\\VocabResponse`.\n\nYou can convert the response into an array by calling the `toArray()` method on it.\n\n```\nVocabCollector::getFor($entity, MyModel::class)-\u003etoArray()\n```\n\n#### BREAK DOWN OF TERMS\n\n\u003cdetails\u003e\n  \u003csummary\u003eEntity\u003c/summary\u003e\n   \u003cp\u003e\n   An entity in your application is an authenticated and unique tenant or user who uses a custom vocabulary for a core concept, different from the standard term.\n    \u003c/p\u003e\n\u003c/details\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eVocab\u003c/summary\u003e\n   \u003cp\u003e\n  The name of the concept you provide, as known or defined by you. By default, the vocab is the model's table name.\n    \u003c/p\u003e\n\u003c/details\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eVocab Mapper\u003c/summary\u003e\n   \u003cp\u003e\n    A mapping of custom names to existing vocabs. It is advisable to store custom names in their plural form. For instance, use \"subjects\" instead of \"subject.\" The VocabResponse will handle the conversion between singular and plural forms in its response.\n    \u003c/p\u003e\n\u003c/details\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eHandler\u003c/summary\u003e\n   \u003cp\u003e\n   The class namespace responsible for managing this vocab, typically the model class for that vocab, but it can also be a non-model class.\n    \u003c/p\u003e\n\u003c/details\u003e\n \n## TESTING\n\n```\nvendor/bin/phpunit\n```\n\nFor console-based coverage tests:\n\n```\nvendor/bin/phpunit --coverage-text\n```\n\nOR\n\nFor html-based coverage tests:\n\n```\n vendor/bin/phpunit --coverage-html test-coverage\n```\n\n## CONTRIBUTING\n\n```\nvendor/bin/testbench workbench:install\n```\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%2Fmonamoxie%2Fvocab-mapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmonamoxie%2Fvocab-mapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonamoxie%2Fvocab-mapper/lists"}