# freento/dimensional-shipping

> Dimensional Shipping module with REST API integration

`composer require freento/dimensional-shipping`

Canonical URL: https://packagento.com/freento/dimensional-shipping

## At a glance

- **Vendor**: Freento (https://packagento.com/freento.md)
- **Latest version**: 1.0.0 — released 2025-12-08
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/freento/dimensional-shipping and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require freento/dimensional-shipping:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

Dimensional Shipping module with REST API integration

## README

A Magento 2 module for calculating shipping costs based on product dimensions using 3D bin packing via REST API.

### Features

- **3D Bin Packing**: Calculates optimal packing of items into shipping boxes via external REST API
- **Product Dimensions**: Custom product attributes for length, width, height, and shipping constraints
- **Multiple Product Types Support**:
  - Simple products
  - Configurable products
  - Bundle products
  - Grouped products
- **Shipping Carrier Integration**: Works with FedEx, UPS, and USPS carriers
- **Package Box Management**: Configure multiple box sizes with dimensions and weight limits
- **Smart Caching**: Stores packing results to avoid redundant calculations
- **Ships Separately Option**: Mark products that must ship in their own box
- **Rotation Control**: Prevent specific items from being rotated during packing
- **Admin UI**:
  - Manage package boxes
  - Import/export product dimensions via CSV
  - View packing results for orders
- **REST API Integration**: Uses external packing service for calculations

### Requirements

- Magento 2.4.7 or higher
- PHP 8.1 or higher
- External Dimensional Shipping REST API service (see API Requirements below)

### Installation

#### 1. Add Module Files

```bash
composer require freento/module-dimensional-shipping
```

Or copy the module to your Magento installation:

```bash
cp -r app/code/Freento/DimensionalShipping /path/to/magento/app/code/Freento/
```

#### 2. Enable the Module

```bash
bin/magento module:enable Freento_DimensionalShipping
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush
```

### Configuration

#### 1. Module Settings

Navigate to: **Stores → Configuration → General → Dimensional Shipping**

Configure the following:

- **Enable Dimensional Shipping**: Yes/No
- **API Key**: Your API key for authenticating with the dimensional shipping REST API service
- **Dimension Unit**: Select unit for dimensions (inches, cm)

**Note**: Weight unit is taken from the global Magento setting: **Stores → Configuration → General → General → Locale Options → Weight Unit**

#### 2. Carrier Configuration

Navigate to: **Stores → Configuration → Sales → Shipping Methods**

For each carrier (FedEx, UPS, USPS):
- **Use Package Dimensions**: Enable to use dimensional shipping with this carrier

These options will only appear when Dimensional Shipping is enabled.

#### 3. Configure Package Boxes

Navigate to: **Dimensional Shipping → Package Boxes**

Add boxes with:
- Name
- Length, Width, Height (in your configured dimension unit)
- Maximum weight (in your configured weight unit)
- Enabled status

Example boxes (in inches):
```
Small Box:  12" × 10" × 8", max 20 lbs
Medium Box: 18" × 14" × 12", max 50 lbs
Large Box:  24" × 18" × 16", max 70 lbs
```

### Product Configuration

#### Adding Dimensions to Products

For each product, configure the following attributes:

##### Required Attributes:
- **Package Length** (`dimensional_shipping_package_length`)
- **Package Width** (`dimensional_shipping_package_width`)
- **Package Height** (`dimensional_shipping_package_height`)
- **Weight** (standard Magento attribute)

##### Optional Attributes:
- **No Rotation Allowed** (`dimensional_shipping_no_rotation_allowed`): Prevent item rotation during packing (useful for fragile items)
- **Ships Separately** (`dimensional_shipping_ships_separately`): Item must ship in its own box

#### Product Types

##### Simple Products
Set dimensions directly on the product.

##### Configurable Products
Set dimensions on the child simple products (selected variant).

##### Bundle Products
Set dimensions on the component simple products.

##### Grouped Products
Set dimensions on the child simple products. The grouped product parent does not need dimensions.

### How It Works

#### 1. Customer Adds Products to Cart

Products with configured dimensions are added to the shopping cart.

#### 2. Shipping Calculation Triggered

When the customer views shipping methods, the module:

1. Collects all cart items and their dimensions
2. Loads configured package boxes
3. Sends data to REST API for optimal packing calculation (authenticated with API key)
4. Receives packed box configurations
5. Caches results to database

#### 3. Packing Results Used

The calculated box dimensions and weights are passed to shipping carriers (FedEx, UPS, USPS) for rate calculation.

#### 4. Smart Caching

The module caches packing results and checks timestamps to determine if recalculation is needed:

- Quote items changed
- Products updated
- Package boxes modified

### Import/Export Product Dimensions

#### Export Dimensions to CSV

Navigate to: **Dimensional Shipping → Package Dimensions**

Click **Export** to download CSV with all product dimensions.

#### Import Dimensions from CSV

Navigate to: **Dimensional Shipping → Package Dimensions**

1. Click **Import**
2. Upload CSV file with columns:
   - `sku`
   - `length`
   - `width`
   - `height`
   - `no_rotation_allowed` (0/1)
   - `ships_separately` (0/1)
3. Click **Import**

### Admin Features

#### View Order Packing Details

Navigate to: **Sales → Orders → View Order**

Under the **Packaging** tab, you can see:
- Which boxes were used
- Item placement within each box
- 3D positions of each item
- Items that couldn't be packed

### Troubleshooting

#### No Shipping Rates Displayed

**Check**:
1. Module is enabled in configuration
2. API Key is correctly configured
3. API service is running and accessible
4. Products have dimension attributes set
5. At least one package box is configured and enabled
6. Carrier's "Use Package Dimensions" option is enabled

**View Logs**:
```bash
tail -f var/log/system.log | grep -i "dimensional"
```

#### API Connection Errors

_(README truncated for .md surface. Full README on https://packagento.com/freento/dimensional-shipping.)_

## Recent Versions

| Version | Released |
|---|---|
| 1.0.0 | 2025-12-08 |

## Dependencies

### Require

| Package | Constraint |
|---|---|
| magento/framework | * |

## Quality

Latest release (1.0.0) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 1 | 1 | – | – |
| 2.4.8 | – | 1 | 1 | – |
| 2.4.9 | – | – | 1 | 1 |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Fail | 49 | 12 errors, 37 warnings (ruleset: Magento2), 12 auto-fixable with phpcbf |
| PHPMD | Warning | 36 | 36 rule violations (UndefinedVariable:8, CyclomaticComplexity:7, NPathComplexity:5, ExcessiveParameterList:4, ExcessiveClassComplexity:3) |
| Cpd | Pass | 0 |  |
| Composer validate | Info | 3 | valid; 3 advisory notes (composer validate --strict) |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 31 | 31 | – | – |
| 2.4.8 | – | 31 | 31 | – |
| 2.4.9 | – | – | 31 | 34 |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["freento/dimensional-shipping"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

Freento is a Magento 2 vendor on Packagento. See https://packagento.com/freento.md for their full catalogue.