Product Attachments for Magento 2 user guide

No coding is needed. Every setting lives in the Magento admin, and the guide walks you through them.

Overview

Product Attachments is a Magento 2 extension from Magexweb that adds manuals, data sheets, certificates, warranty terms, drawings, links and videos to your product pages. Customers find everything they need on the product page, in a clear list, grid or table, and download files with one click.

Attachments are organised in three levels: document types (such as User Manual or Warranty) describe what a file is, attachments are the files, links and videos themselves, and attachment groups bundle attachments and are assigned to products. One group can be shown on thousands of products, and one attachment can be used in several groups, so a shared document is uploaded only once.

Important: Files are stored with random names in a protected folder and are only delivered through a download address that checks the status, the store view and the customer's access every time. On nginx, add the deny rule from Web server configuration so stored files cannot be opened directly.

Key features

  • Three kinds of attachments: uploaded files (PDF, Word, Excel, PowerPoint, ZIP, images), external links and videos (YouTube, Vimeo or an MP4, WEBM or OGG file)
  • Document types with 14 built-in icons, uploaded icons or icon classes from your theme
  • Attachment groups in three display styles (list, grid, table), optionally grouped by document type
  • Five product page positions: after the title, after the short description, before the tabs, after the tabs or in a new product tab
  • Assign groups from the group (filterable product grid) or from the product edit page
  • Access control per attachment and per group: everyone, logged-in customers only or chosen customer groups, plus store-wide rules
  • Restricted attachments are hidden or shown with a "Log in to access" button
  • Videos play in a popup on the product page; nothing is loaded from YouTube or Vimeo before the customer clicks
  • Secure uploads: allowed file types, size limit, content (MIME) check, scripts always refused, random file names, protected storage
  • Downloads save the file directly; PDFs and images can optionally open in the browser
  • Store view assignment for attachments and groups
  • REST API for document types, attachments (with file upload), groups and product assignments
  • Sample data, granular admin permissions and full page cache support

How it works

Create document types, attachments and a group, then assign the group to products. Each group appears on the product page in its position with its name, description and attachments. Here a grid group is shown below the product information, before the tabs:

Product video in a grid group before the product tabs

Groups in the New Product Tab position appear in their own tab, called "Downloads" by default. This group uses the list style and is grouped by document type; the second group is only available to logged-in customers:

Downloads tab with attachments grouped by document type and a login-only group

On phones, attachments and buttons use the full width of the screen:

Product attachments on a phone

Requirements and compatibility

  • Magento Open Source or Adobe Commerce 2.4.8 or 2.4.9
  • PHP 8.2 to 8.4 with the sodium extension (required by Magento)
  • Luma, Blank and Luma-based themes
  • Magento cron, which removes uploads that were never saved

Installation

Composer installation (recommended)

  1. Place the extension in your project: through the Adobe Commerce Marketplace, a private Composer repository, or by copying it under app/code.
  2. From the Magento root, run the commands below.
CommandPurpose
composer require magexweb/module-product-attachmentsOnly if installed from a Composer repository
php bin/magento module:enable Magexweb_ProductAttachmentsRegisters and enables the module
php bin/magento setup:upgradeCreates the product attachment tables
php bin/magento setup:di:compileRecommended for production mode
php bin/magento setup:static-content:deploy -fRequired in production mode
php bin/magento cache:flushClears the Magento cache

Manual (ZIP) installation

  1. Extract the ZIP package to app/code/Magexweb/ProductAttachments, so that app/code/Magexweb/ProductAttachments/registration.php exists.
  2. Run the same bin/magento commands as above.
  3. Check that the module is active: php bin/magento module:status Magexweb_ProductAttachments

Sample data

Install the sample data to see the extension in action straight away: 6 document types (User Manuals, Specifications, Installation, Warranty, Safety & Compliance, Videos), 11 attachments (9 sample PDF, PNG and ZIP files, a "Register Your Product" link and a sample video) and 4 groups, one per display style and position.

CommandPurpose
php bin/magento magexweb:productattachments:sample-data:installInstalls the sample data and assigns the groups to the first three enabled products visible in catalog and search
php bin/magento magexweb:productattachments:sample-data:install --sku=24-MB01 --sku=24-MB04,24-WB01Assigns the groups to the products you choose (repeat --sku or separate SKUs with commas)
php bin/magento magexweb:productattachments:sample-data:removeRemoves exactly what was installed, including the files. Your own attachments are never touched.

Note: Sample identifiers start with sample-. If an identifier is already used in your store, the sample item gets a number added instead of replacing your content. Sample files of a type that is not in Allowed Extensions are skipped.

Web server configuration

Stored files are in pub/media/magexweb/productattachments/files/ and are only delivered through the protected download address.

  • Apache: the module writes .htaccess files that deny direct access to the files/ and tmp/ folders. Nothing else is needed.
  • nginx: nginx ignores .htaccess files. Add this rule to the server block that serves pub/, next to Magento's own rules for /media/customer/ and /media/downloadable/:
location ~ ^/media/magexweb/productattachments/(files|tmp)/ {
    deny all;
}

After installing

  1. Check the upload limits and allowed file types in the configuration.
  2. Create document types, then attachments, then groups, and assign the groups to products.
  3. Make sure Magento cron runs: it removes uploads that were never saved.

Admin configuration

All settings live under Stores > Settings > Configuration > Magexweb Extensions > Product Attachments, also available from Product Attachments > Configuration. Use the scope switcher at the top of the page for different settings per website or store view; settings marked "global" apply to the whole installation.

Product Attachments menu in the Magento admin

General

General settings of Product Attachments
FieldDescription
Enable Product AttachmentsMaster switch. Set to No to hide all attachments and refuse downloads in this store view. Your data and files are kept.
Default: Yes
Debug ModeWrites diagnostic messages to var/log/magexweb_productattachments.log. Scope: global.
Default: No

File upload

File upload settings: maximum file size and allowed extensions
FieldDescription
Maximum File Size (MB)Largest file accepted by uploads in the admin and through the API. PHP's upload_max_filesize and post_max_size must be at least as large (the admin shows the current limit). Scope: global.
Default: 20 MB
Allowed ExtensionsComma-separated, for example pdf,docx,zip. Scope: global.
Default: pdf,doc,docx,xls,xlsx,ppt,pptx,zip,jpg,jpeg,png,webp
Storage LocationInformation only. Scope: global.

Note: Executable and script file types (such as php, phtml, phar, js, html, exe and sh) are always refused, even if they are added to Allowed Extensions. Add svg only if you trust every administrator who uploads files.

Frontend

Frontend settings: display style, icons, file size and video display
FieldDescription
Default Display StyleStyle of groups set to "Use Default Display Style": List, Grid or Table.
Default: List
Show IconsShows the document type icon or the coloured file type tile next to each attachment.
Default: Yes
Show DescriptionShows the description of attachments and groups.
Default: Yes
Show File Type and SizeShows the file type badge and the size, for example "PDF 2.4 MB".
Default: Yes
Open Downloads in New TabDefault of Open in New Tab for new attachments. It applies to links and videos; files download directly unless Open PDFs and Images in Browser is enabled.
Default: Yes
Video DisplayEmbedded Player (loads on click): Watch Video plays the video in a popup on the page. Link to Video: the button opens the video on YouTube, Vimeo or the file URL.
Default: Embedded Player (loads on click)
Enable Lazy LoadingLazy-loads thumbnails and only loads the YouTube or Vimeo player after the customer clicks play.
Default: Yes

Access

Store-wide access settings for product attachments
FieldDescription
Require Login for All AttachmentsApplies on top of each attachment's and group's own access settings.
Default: No
Restrict to Customer GroupsLimits all attachments to the customer groups selected below, on top of each attachment's and group's own rules.
Default: No
Allowed Customer GroupsCustomer groups that may see attachments when Restrict to Customer Groups is Yes. Include NOT LOGGED IN to allow guests.
Default: None selected
Hide Restricted AttachmentsNo: visitors who may not open an attachment see it with a lock and a Log in to access button. Yes: such attachments are hidden completely.
Default: No

Product page

Product page settings: default position, enabled positions and tab title
FieldDescription
Default PositionUsed by groups set to "Use Default Position".
Default: New Product Tab
Enabled PositionsGroups assigned to a disabled position are not shown.
Default: All five positions
Product Tab TitleTitle of the product tab used by groups in the New Product Tab position.
Default: Downloads
Section HeadingHeading shown above attachments outside the product tab. Leave empty to show group names only.
Default: Product Documents

Security

Security settings: MIME type validation and opening PDFs in the browser
FieldDescription
Validate MIME TypesChecks that file contents match the extension on upload. Strongly recommended. Scope: global.
Default: Yes
Open PDFs and Images in BrowserNo (recommended): clicking Download saves the file directly without leaving the page. Yes: PDFs and images open in a new browser tab. SVG and other types are always downloaded. Scope: global.
Default: No

Note: Some browsers (for example Firefox, Safari and Edge) open PDFs automatically after saving them. This is a browser setting: the extension tells the browser to save the file, and it is saved in the Downloads folder.

Document types

Document types describe what an attachment is, for example User Manual, Data Sheet or Warranty. They give attachments an icon, and groups can list their attachments under a heading per document type. Manage them in Product Attachments > Document Types.

Document types grid in the Magento admin

Adding a document type

Click Add New Document Type and fill in:

New document type form
FieldDescription
EnabledDisabled document types are not shown as headings or chips on the storefront.
NameShown to customers, for example "User Manuals".
IdentifierUnique code with lowercase letters, digits, "-" and "_", for example user-manual. Used by the API.
DescriptionInternal description (optional).
Sort OrderOrder of the document type headings when a group is grouped by document type.
Choosing a built-in icon for a document type
Icon typeDescription
No IconThe file type icon is used (PDF, document, spreadsheet and so on).
Built-in IconOne of 14 icons: Document, PDF, Spreadsheet, Presentation, Archive, Image, Video, Link, Manual / Book, Warranty / Shield, Installation / Tools, Specification / Checklist, Safety / Warning and Download.
Uploaded ImageYour own JPG, PNG, GIF or WEBP icon. SVG is not accepted, for security reasons.
CSS ClassA class from your theme's icon font, for example icon icon-warranty.

Attachments

Attachments are the files, links and videos your customers see. Manage them in Product Attachments > Attachments. The grid shows each attachment's type, document types, status and the number of products it is shown on. Filter by type, status, access or document type, and use the Actions menu to enable, disable or delete several attachments at once.

Attachments grid with type, document types, status and product count

Adding an attachment

Click Add New Attachment. The form has four sections.

Attachment Information: the title, an optional description and the attachment itself.

Attachment information: title, description, type, file and thumbnail
FieldDescription
EnabledDisabled attachments are not shown and cannot be downloaded.
TitleShown to customers and used as the button's accessible label.
DescriptionPlain text shown below the title. Line breaks are kept; HTML is shown as text.
Attachment TypeFile Upload, External URL or Video. The fields below change with the type.
FileFor File Upload. The allowed types and the maximum size are shown below the button. Uploading a new file replaces the old one.
ThumbnailOptional preview image (JPG, PNG, GIF or WEBP, up to 5 MB), recommended for videos.

For External URL and Video attachments, enter the address instead of uploading a file:

URL and link label fields for a link or video attachment
  • URL: must start with http:// or https://. Addresses with a user name or password, javascript: and data: addresses are refused.
  • Link Label (External URL only): optional button text, for example "Register Now". The default is "Open Link".
  • Videos: YouTube (watch, youtu.be, shorts and embed links), Vimeo (including unlisted videos) or a direct link to an MP4, WEBM or OGG file.

Document Types: choose one or more. The first one (lowest sort order) gives the attachment its icon and decides under which heading it is listed in grouped groups.

Choosing document types for an attachment

Frontend & Access:

Frontend and access settings of an attachment
FieldDescription
Display on Product PageSwitch off to keep the attachment out of product pages, for example to use it through the API only.
Open in New TabFor external links and videos. Files download directly, unless Open PDFs and Images in Browser is enabled in the configuration.
Who Can AccessEveryone, Logged-in Customers Only or Specific Customer Groups. With the last option a Customer Groups list appears; include NOT LOGGED IN to allow guests. See Customer access control.

Store Views & Advanced:

Store views, attachment groups and sort order of an attachment
FieldDescription
Store ViewsAll Store Views or specific store views.
Attachment GroupsThe groups this attachment belongs to. It is shown on every product these groups are assigned to. You can also add attachments from the group.
Sort OrderDefault order of attachments; the order inside a group is set in the group.

Supported files

The default allowed extensions are pdf, doc, docx, xls, xlsx, ppt, pptx, zip, jpg, jpeg, png and webp, up to 20 MB. You can change both in the configuration. Every upload, in the admin and through the API, is checked:

  • The extension must be allowed; script and executable types are always refused.
  • The file content must match the extension (a PDF must really be a PDF), and dangerous content types are refused.
  • SVG, TXT, CSV and RTF files are scanned for scripts, event handlers and embedded objects.
  • The file is stored under a random name; the original name is only used, cleaned, as the download name.

Attachment groups

A group bundles attachments, decides how and where they are shown, and is assigned to products. Manage groups in Product Attachments > Attachment Groups.

Attachment groups grid

Adding a group

Click Add New Attachment Group. General:

General settings of an attachment group
FieldDescription
EnabledDisabled groups are not shown, and their attachments cannot be downloaded through them.
NameShown as the heading of the group on the product page.
IdentifierUnique code, for example product-documentation.
DescriptionOptional plain text shown below the heading.
Sort OrderDefault order of groups in the same position.

Attachments of the group

In the Attachments section, click Add Attachments, tick the attachments in the dialog and click Add Selected Attachments. Search and filter the dialog to find attachments quickly; attachments already in the group are not added twice.

Add Attachments dialog with search and filters

Drag the rows to change the order in which the attachments are shown, and use Remove to take an attachment out of the group. The attachment itself is not deleted.

Attachments of a group, sorted by dragging

Display, access and store views

Display style, position and grouping by document type
FieldDescription
Display StyleList: one attachment per row with a large button. Grid: cards side by side. Table: compact rows with type, size and button columns. Use Default Display Style follows the configuration.
Product Page PositionAfter Product Title, After Short Description, Before Product Tabs, After Product Tabs or New Product Tab. Use Default Position follows the configuration.
Group Attachments by Document TypeShows a sub-heading per document type. An attachment with several types is listed under its first type.

Who Can See This Group works as for attachments: a customer must be allowed by both the group and the attachment. Store Views limits the group to store views.

Who can see an attachment group
Store views of an attachment group

Assigning groups to products

There are two ways to choose the products a group is shown on. Both work for large catalogs.

From the group

Open the Products section of the group. The grid first shows the products already assigned. Set the checkbox column filter to Any or No to find other products, filter by ID, name, SKU, type, visibility, status or price, and tick or untick products (clicking a row toggles it). Your ticks are kept while you filter and page. Click Save to apply them; this also works for a new group before its first save.

Assigning an attachment group to products from a filterable product grid

From the product

On the product edit page (Catalog > Products), open the Product Attachments section, click Add Attachment Group, choose a group and enter a position, then save the product. The position decides the order of several groups on that product; use the bin icon to remove a group from the product.

Product Attachments section on the Magento product edit page

Note: Assigning groups requires the "Assign Groups to Products" permission (see Admin permissions). Without it the group's Products section shows a message instead of the grid, and the Product Attachments section is not shown on the product edit page.

Storefront behaviour

Positions

Each group is shown in its position on the product page. Positions can be switched off in Configuration > Product Page > Enabled Positions.

PositionWhere it appears
After Product TitleBelow the product name, above the price
After Short DescriptionBelow the short description in the product information area
Before Product TabsBelow the product information and image gallery, above the tabs
After Product TabsBelow the tabs (Details, Reviews and so on)
New Product TabIn its own tab, titled "Downloads" by default (Product Tab Title)

Outside the product tab, attachments get the heading set in Section Heading ("Product Documents" by default).

Display styles

List (shown in How it works): one attachment per row with icon, title, type badge, size, document types, description and a large button. Grid: cards side by side, ideal for videos and images:

Attachments in the grid display style

Table: compact rows for many documents, with document type, file type and size columns:

Attachments in the table display style

Downloads, links and videos

  • Files: the Download button saves the file directly without leaving the page. With Open PDFs and Images in Browser enabled, PDFs and images open in a new tab instead.
  • Links: the Open Link button (or your Link Label) opens the address, in a new tab if Open in New Tab is enabled.
  • Videos: Watch Video plays the video in a popup. Close it with the × button, the Esc key or a click outside the video; the video stops when the popup closes. Nothing is loaded from YouTube or Vimeo until the customer clicks, and YouTube videos use the privacy-enhanced youtube-nocookie.com domain.
Product video playing in a popup

Restricted attachments

When a visitor may not open an attachment, it is shown with a lock and a Log in to access button that leads to the login page. After logging in, the customer can download it. Set Hide Restricted Attachments to Yes to hide such attachments completely.

Restricted attachments with a Log in to access button

Note: Downloads always go through the protected address /magexweb_attachments/download/index/id/<id>/. A file is only delivered when the attachment and at least one of its groups are enabled, assigned to the store view and allowed for the visitor; otherwise the visitor sees the 404 page (or, for login-only files, the login page).

Customer access control

Access is checked on three levels. A visitor can open an attachment only when all three allow it:

LevelWhereOptions
Store-wideConfiguration > AccessRequire Login for All Attachments; Restrict to Customer Groups
GroupAttachment group > AccessEveryone, Logged-in Customers Only, Specific Customer Groups
AttachmentAttachment > Frontend & AccessEveryone, Logged-in Customers Only, Specific Customer Groups

New attachments and groups are available to everyone. Examples:

GoalSetting
Price lists for wholesale customers onlyAttachment: Specific Customer Groups > Wholesale
CAD drawings for registered customersGroup or attachment: Logged-in Customers Only
Hide all attachments from guestsConfiguration: Require Login for All Attachments = Yes
Guests should not even see restricted itemsConfiguration: Hide Restricted Attachments = Yes

An attachment that is in several groups can be opened when at least one of its groups allows the visitor. The rules also apply to direct download links: copying a link does not get around them.

Multiple store views

  • Assign attachments and groups to All Store Views or to specific store views.
  • Titles and descriptions of attachments, groups and document types are the same in every store view. For text in another language, create a separate attachment and assign it to that store view.
  • Configuration settings can be changed per website or store view where the scope switcher allows it.

Security

  • Uploads: allowed extensions only, executable and script types always refused, size limit, content (MIME) check, scripts in SVG, TXT, CSV and RTF refused, random file names, protected storage folder.
  • Downloads: status, store view and customer access are checked for every download. Files are sent with headers that stop browsers from running them (X-Content-Type-Options: nosniff, a sandbox Content Security Policy), are never cached by proxies (Cache-Control: private, no-store) and are not indexed by search engines (X-Robots-Tag: noindex).
  • Admin: every screen and action has its own permission; saving, deleting, uploading and mass actions require a POST request with Magento's form key.
  • API: every endpoint requires the matching permission. File size, type and extension are always read from the stored file, and storage paths are never returned.
  • Output: titles, descriptions and labels are escaped; links must be http(s) and get rel="nofollow noopener noreferrer"; video players are built from validated video IDs only.
  • Logging: only IDs, sizes and errors are logged, never customer data or file contents. Debug messages are written only when Debug Mode is on.

Admin permissions

In System > Permissions > User Roles > Role Resources > Product Attachments, each area is a separate permission, so you can give staff exactly the access they need:

ResourceAllows
AttachmentsView attachments; Save Attachments and Delete Attachments are separate permissions
Document TypesView document types; Save Document Types; Delete Document Types
Attachment GroupsView groups; Save Attachment Groups; Delete Attachment Groups
Assign Groups to ProductsAssign groups in the group's Products section, on the product edit page and through the API
Product Attachments ConfigurationStores > Configuration > Product Attachments

REST API

All endpoints are under /rest/V1/productattachments and need an admin or integration token (Authorization: Bearer <token>) with the matching Product Attachments permission. Use /rest/<store_code>/V1/... for a store view context.

EndpointDescription
GET /document-types, /document-types/:id, /document-types/code/:codeList or get document types
POST /document-types, PUT /document-types/:id, DELETE /document-types/:idCreate, update or delete a document type
GET /attachments, /attachments/:idList or get attachments
POST /attachmentsCreate a link or video attachment
POST /attachments/with-fileCreate a file attachment with its file (base64)
PUT /attachments/:id, PUT /attachments/:attachmentId/fileUpdate an attachment or replace its file
DELETE /attachments/:idDelete an attachment and its file
GET /groups, /groups/:id, /groups/code/:codeList or get groups
POST /groups, PUT /groups/:id, DELETE /groups/:idCreate, update or delete a group
GET, POST /groups/:groupId/productsGet or replace the products of a group ([{sku, position}])
GET, POST /products/:sku/groupsGet or replace the groups of a product ([{group_id, position}])

Example: create a file attachment with POST /rest/V1/productattachments/attachments/with-file:

{
  "attachment": {"title": "Installation Guide", "is_active": true, "document_type_ids": [3], "store_ids": [0]},
  "file": {"name": "installation-guide.pdf", "base64_encoded_data": "JVBERi0xLjQK..."}
}
  • PUT changes only the fields you send; relations (document types, store views, groups) are replaced only when they are sent.
  • API uploads go through the same checks as admin uploads. Validation errors return 400 with every problem listed; unknown records return 404.
  • file_size, file_mime and file_extension are read-only and always describe the stored file; file_name is the download name and keeps the extension of the stored file.

Note: Bearer tokens require the web server to pass the Authorization header to PHP. Magento's pub/.htaccess does this; check your setup if the document root is not pub.

Cron jobs and commands

Cron jobSchedulePurpose
magexweb_productattachments_clean_tmpDaily at 03:15Deletes uploads that were never saved (older than 24 hours)
CommandPurpose
magexweb:productattachments:sample-data:install / :removeInstall or remove the sample data
magexweb:productattachments:clean-tmpDelete abandoned uploads now (--hours=1 for uploads older than one hour)

Uninstallation

To switch the extension off but keep everything, set Configuration > General > Enable Product Attachments to No, or run php bin/magento module:disable Magexweb_ProductAttachments. Data and files are kept.

To remove it completely:

  1. Optional: php bin/magento magexweb:productattachments:sample-data:remove
  2. php bin/magento module:disable Magexweb_ProductAttachments
  3. Composer: composer remove magexweb/module-product-attachments. Manual installation: delete the app/code/Magexweb/ProductAttachments folder.
  4. Optionally delete the data: the tables starting with magexweb_productattachment_, the configuration (core_config_data paths starting with magexweb_productattachments/), the module's setup_module row and the folder pub/media/magexweb/productattachments/.
  5. php bin/magento setup:upgrade, php bin/magento setup:di:compile and php bin/magento cache:flush

Important: Back up your database and the pub/media folder before deleting data: attachments, groups and files are deleted permanently.

Troubleshooting and FAQ

QuestionAnswer
Nothing appears on the product pageCheck that the extension is enabled, the group is enabled and assigned to the product and store view, its position is enabled in the configuration, and the attachments are enabled with Display on Product Page. Then refresh the Page Cache.
The Download button shows a 404 pageThe attachment or all of its groups are disabled or not in this store view, the visitor is not allowed, or the file is missing. Debug Mode writes details to var/log/magexweb_productattachments.log.
An upload is refusedThe file type is not in Allowed Extensions, the file is larger than the limit (also check PHP's upload_max_filesize and post_max_size), or its content does not match the extension.
A PDF opens in the browser although Open PDFs and Images in Browser is NoYour browser opens PDFs after saving them (Firefox, Safari and Edge can do this). The file is saved; change the browser's download setting for PDF files.
Stored files can be opened directly on nginxAdd the deny rule from Web server configuration.
Old uploads pile up in the tmp folderCron is not running. Run php bin/magento magexweb:productattachments:clean-tmp.
The video does not play in the popupCheck the URL (YouTube, Vimeo or an MP4, WEBM or OGG file). With Content Security Policy in restrict mode, add youtube-nocookie.com, player.vimeo.com or your video host to the CSP whitelist (frame-src or media-src).
Changes are not visible on the product pageFlush the Page Cache in System > Cache Management.

Support

For help, contact Magexweb at info@magexweb.com. Please include your Magento version, PHP version, a description of the problem and, if possible, var/log/magexweb_productattachments.log (enable General > Debug Mode for details).

Tell us about your project.

Share a few details and we will reply with questions, a recommended approach and next steps.

  • Email info@magexweb.com
  • Phone +91 99092 71288
  • Hours Mon–Fri, 10:00 AM to 8:00 PM IST
  • Office D-1002, Jasmin Green 1, Near Vaishnodevi Circle, Ahmedabad 382421, India

  • Free consultation
  • NDA available
  • Reply by email