{"id":19250263,"url":"https://github.com/charcoalphp/attachment","last_synced_at":"2026-06-23T10:31:46.608Z","repository":{"id":37806401,"uuid":"505905457","full_name":"charcoalphp/attachment","owner":"charcoalphp","description":"[READ-ONLY] Adds support for working with relationships between models.","archived":false,"fork":false,"pushed_at":"2024-03-13T15:05:16.000Z","size":358,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-14T11:51:16.231Z","etag":null,"topics":["attachment","blocks","charcoal","content","php","read-only-repository"],"latest_commit_sha":null,"homepage":"https://github.com/charcoalphp/charcoal","language":"PHP","has_issues":false,"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/charcoalphp.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}},"created_at":"2022-06-21T15:42:13.000Z","updated_at":"2022-06-21T19:30:37.000Z","dependencies_parsed_at":"2024-01-13T04:49:48.176Z","dependency_job_id":"0b3ebd7f-f14e-47f5-8797-0e62622c8784","html_url":"https://github.com/charcoalphp/attachment","commit_stats":{"total_commits":227,"total_committers":13,"mean_commits":17.46153846153846,"dds":0.5903083700440528,"last_synced_commit":"92e43e58e07e2c4c36082cd46c40e4e6bc3e1f51"},"previous_names":[],"tags_count":83,"template":false,"template_full_name":null,"purl":"pkg:github/charcoalphp/attachment","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fattachment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fattachment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fattachment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fattachment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/charcoalphp","download_url":"https://codeload.github.com/charcoalphp/attachment/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fattachment/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34686725,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"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":["attachment","blocks","charcoal","content","php","read-only-repository"],"created_at":"2024-11-09T18:16:39.356Z","updated_at":"2026-06-23T10:31:46.592Z","avatar_url":"https://github.com/charcoalphp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Charcoal Attachment\n===================\n\nThe Attachment package provides support for working with relationships between models.\n\n## Installation\n\n```shell\ncomposer require charcoal/attachment\n```\n\n## Overview\n\nThe package also provides a collection of basic attachments: Document, Embed, Image, Gallery, Link Video, amongst others.\n\n### Objects\n\nObjects in the Attachment package extend `Content`, from [charcoal/object], which is an `AbstractModel`, from [charcoal/core].\n\nIn addition from the default metadata provided by `Content`, the following properties are default for all `Attachment` objects:\n\n**Standard properties** (used by all attachments objects):\n\n| Property        | Type      | Description |\n| --------------- | --------- | ----------- |\n| **id**          | `id`      | A uniqid, for referencing. |\n| **title**       | `string` (l10n) | \n| **show_title**  | `boolean` |\n| **categorie**   | `object (multiple) | By default, categories are `charcoal/attachment/object/category/generic` objects.\n| **subtitle**    | `string` (l10n) |\n| **description** | `text` (l10n) |\n| **keywords**    | `string` (l10n, multiple) | Typically used for searching purpose. |\n| **type**        | `string`  |\n\n**Specialized properties** which can be used differently, depending on context:\n\n| Property        | Type      | Description |\n| --------------- | --------- | ----------- |\n| **link**        | `string` (l10n) | URL. |\n| **file**        | `file` (l10n)   | Uploadable file, or \"document\". |\n| **file_size**   | `string`  | The uploaded file size, in bytes (auto-generated). |\n| **file_type**   | `string`  | The uploaded file mimetype (auto-generated).\n| **thumbnail**   | `image` (l10n)  | \n| **embed**       | `text` (l10n)   | Typically a video. |\n\nAll attachments are assumed to have a `title`, `subtitle`, `description` and `keywords`. Some attachments also \n\n\u003e Read the [charcoal/object] documentation for the other default properties provided by the `Content` object (and `RevisionableInterface`).\n\n\u003e Read the [charcoal/core] documention for the other default properties provided by `AbstractModel` (and `DescribableInterface` and `StorableInterface`). \n\n#### Type of Attachment objects\n\n-   **Accordion**\n    - A `Container` (grouping) attachment, used for accordion type of display.\n    - By default, support `text`, `image`, `gallery` and `embed` attachments.\n-   **Attachment**\n    - The most generic attachment, can be anything.\n-   **Container**\n    - Base \"grouping\" attachment.\n-   **Embed**\n    - Embedded content, typically video embed code.\n    - Force the `file` property to be an `image`, and `description` to be `html`.\n-   **File**\n    - An uploadable _Document_.\n-   **Link**\n    - A URL (link to a resource).\n-   **Image**\n    - An uploadable image\n    - Force the `file` property to be an `image`.\n-   **Gallery**\n    - A `Container` (grouping) attachment, used for a gallery of multiple images.\n    - Is limited to `image` attachments.\n-   **Text**\n    - Text (HTML) content.\n-   **Video**\n\n### Widgets\n\nThe packages provides its own admin widgets namespaced as `Charcoal\\Admin`.\n\nThe attachment widget can be use more than once in a form. In order for it to work properly, you need to define a group ident `group` different for each instanciated widgets.\n\n```json\n\"attachment\": {\n    \"type\": \"charcoal/admin/widget/attachment\",\n    \"group\": \"main\"\n}\n```\n\nIn this case, we set the group to \"main\". If none defined, the default group will be \"generic\". Without those ident, widgets won't be able to know which attachments are his.\n\nYou can than access a perticular \"group\" attachments calling the object's method \"attachments(group_ident)\". In this case, `$object-\u003eattachments('main')` will return attachments associated with the widgets that has the group set to \"main\".\n\n## Configuration\n\nAdd the views path and metadata path to the config file.\n\n```json\n\"metadata\": {\n    \"paths\": [\n        \"...\",\n        \"vendor/charcoal/attachment/metadata/\"\n    ]\n},\n\"view\": {\n    \"paths\": [\n        \"...\",\n        \"vendor/charcoal/attachment/templates/\"\n    ]\n},\n\"translations\": {\n    \"paths\": [\n        \"...\",\n        \"vendor/charcoal/attachment/translations/\"\n    ]\n}\n```\n\nThen, we need to add the necessary routes for the widgets in admin.json config file.\n\n```json\n\"routes\": {\n    \"actions\": {\n        \"join\": {\n            \"ident\": \"charcoal/admin/action/join\",\n            \"methods\": [ \"POST\" ]\n        },\n        \"add-join\": {\n            \"ident\": \"charcoal/admin/action/add-join\",\n            \"methods\": [ \"POST\" ]\n        },\n        \"remove-join\": {\n            \"ident\": \"charcoal/admin/action/remove-join\",\n            \"methods\": [ \"POST\" ]\n        }\n    }\n}\n```\n\n## Usage\n\nYou need to make your object(s) \"Attachment Aware\", so that it knows it can have attachments. To do that, use/implement attachmentAware:\n\n```php\nuse Charcoal\\Attachment\\Traits\\AttachmentAwareTrait;\nuse Charcoal\\Attachment\\Interfaces\\AttachmentAwareInterface;\n```\n\nThen, just add in the widget in the edit dashboard or the form like this:\n\n```json\n\"attachment\": {\n    \"title\": \"Documents\",\n    \"type\": \"charcoal/admin/widget/attachment\",\n    \"group\": \"main\",\n    \"attachable_objects\": {\n        \"charcoal/attachment/object/file\": {\n            \"label\": \"Document / File\"\n        }\n    }\n}\n```\n\nAvailable attachable objects as provided by the current modile are:\n\n* `charcoal/attachment/object/image`\n* `charcoal/attachment/object/gallery`\n* `charcoal/attachment/object/file`\n* `charcoal/attachment/object/link`\n* `charcoal/attachment/object/text`\n* `charcoal/attachment/object/video`\n\nTo create a new attachment, you need to extend the base Attachment object `charcoal/attachment/object/attachment` and provide a \"quick\" form.\n\nTo remove unnecessary join when deleting an object, you need to add this to your object:\n\n```php\npublic function preDelete()\n{\n    // AttachmentAwareTrait\n    $this-\u003eremoveJoins();\n    return parent::preDelete();\n}\n```\n\n### Attachment creation\n\nThe one thing you need to know about the attachment is that it is all in a single table. You can't associate custom objects with other objects if they are not `attachments`.\n\nThen, how could you create new attachments? It all depends on what you want.\n\n#### Adding or modifying properties\n\nIF you need to add properties to an existing attachment, you can always extend it. Let's say you want to change the editor options for the description field given with the attachments. The first step is to create a new object that will extend the existing one.\n\n```php\n/**\n * Extended text class.\n */\nnamespace My\\Namespace;\n\nuse Charcoal\\Attachment\\Object\\Text as AttachmentText;\n\nclass Text extends AttachmentText\n{\n}\n```\n\nNow that we have the extend, let's add to the JSON by creating a `my/namespace/text.json` file.\n\n```JSON\n{\n    \"properties\": {\n        \"description\": {\n            \"editor_options\": {\n                \"style_formats\": [],\n                \"body_class\": \"s-wysiwyg\",\n                \"content_css\": \"../../../../../styles/main.css\"\n            }\n        }\n    },\n    \"data\": {\n        \"type\": \"my/namespace/text\"\n    }\n}\n```\n\nIn that case, the editor options are changed to remove the base style formats, change the body class and add the appropriate css. The important part is to set the data type to the current object. This is used in live edit and delete features.\n\nIf you added some extra properties, you can use the alter script to add them into the table.\n\n`vendor/bin/charcoal admin/object/table/alter --obj-type=my/namespace/text`\n\n## Notes\n\n**Don't use \"attachments\" method directly in mustache template**. This will return ALL attachments without considering the group.\n\nCustom templates for the attachment preview in the backend widget is on the to-do list.\n\nOther actions such quick view are on the to-do list as well.\n\n## Resources\n\n* [Contributing](https://github.com/charcoalphp/.github/blob/main/CONTRIBUTING.md)\n* [Report issues](https://github.com/charcoalphp/charcoal/issues) and\n  [send pull requests](https://github.com/charcoalphp/charcoal/pulls)\n  in the [main Charcoal repository](https://github.com/charcoalphp/charcoal)\n\n[charcoal/core]:   https://github.com/charcoalphp/core\n[charcoal/object]: https://github.com/charcoalphp/object\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharcoalphp%2Fattachment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharcoalphp%2Fattachment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharcoalphp%2Fattachment/lists"}