# Channel Orders — Courier Icons

## Where the icons live

Courier icons are stored in one location (public assets only — no source/plugin copy needed):

```
public/vendor/channels/couriers/
```

Each file is named after the courier using lowercase with hyphens:

| File | Courier |
|------|---------|
| `royal-mail.svg` | Royal Mail |
| `dpd.svg` | DPD |
| `dx.svg` | DX |
| `evri.svg` | Evri |
| `yodel.svg` | Yodel |
| `customer-collection.svg` | Customer Collection |
| `local-delivery.svg` | Local Delivery |

Icons are displayed in two places:
- **List view** — Shipping Info column (56px)
- **Order view** — Shipping section (72px)

### Icon-only display behaviour

**If an icon file exists for the courier, the text name is hidden — the icon alone is shown.**
If no icon file exists for a courier, the courier name is shown as plain text fallback.

This means you can suppress the text label for any courier simply by providing an icon. Conversely, if you remove an icon file, the name will automatically reappear as text.

---

## How icons are loaded (PHP)

The `courierIconHtml()` private static method in:

```
plugins/webkul/channel-orders/src/Filament/Resources/OrderResource.php
```

contains a `$slugs` array that maps the stored carrier value (e.g. `"Royal Mail"`) to the SVG filename slug (e.g. `"royal-mail"`). It builds an `<img>` tag pointing to the public path.

If the file does not exist for a given courier, no icon is shown — it degrades gracefully.

---

## Where to get SVG icons

Search for the courier name on either site, download the SVG, then drop it into the couriers folder. Real brand logos will automatically hide the courier name text (icon-only display).

- **[https://iconape.com/](https://iconape.com/)**
- **[https://brandlogos.net/](https://brandlogos.net/)**

---

## Replacing an existing courier icon

1. Download the SVG from [iconape.com](https://iconape.com/) or [brandlogos.net](https://brandlogos.net/)
2. Save it directly to `public/vendor/channels/couriers/{slug}.svg`, replacing the existing file

That's it. No PHP changes needed — the helper reads the file at render time.

**Example — replacing the Royal Mail icon:**
```bash
# Drop your new file here, overwriting the existing one:
public/vendor/channels/couriers/royal-mail.svg
```

---

## Adding a new courier

Two changes are required: a new SVG file and two code additions.

### Step 1 — Create the SVG icon

Save it to:
```
public/vendor/channels/couriers/{your-slug}.svg
```

Use a slug that is lowercase with hyphens and no spaces, e.g. `evri.svg`, `ups.svg`.

### Step 2 — Add the option to the form dropdown

In `OrderResource.php`, find the `Select::make('shipping_carrier')` block inside `form()` and add your new entry to the `->options([...])` array:

```php
Select::make('shipping_carrier')
    ->label('Courier')
    ->options([
        'Royal Mail'          => 'Royal Mail',
        'DPD'                 => 'DPD',
        'DX'                  => 'DX',
        'Yodel'               => 'Yodel',
        'Customer Collection' => 'Customer Collection',
        'Local Delivery'      => 'Local Delivery',
        'Evri'                => 'Evri',   // <-- add your new courier here
    ])
    ->searchable(),
```

### Step 3 — Add the slug mapping to the icon helper

In the same file, find the `courierIconHtml()` method and add your new courier to the `$slugs` array. The key must match the value stored in the database (what you put in `->options()`), and the value must match the SVG filename without the `.svg` extension:

```php
private static function courierIconHtml(?string $carrier, int $size = 20): string
{
    // ...
    $slugs = [
        'Royal Mail'          => 'royal-mail',
        'DPD'                 => 'dpd',
        'DX'                  => 'dx',
        'Yodel'               => 'yodel',
        'Customer Collection' => 'customer-collection',
        'Local Delivery'      => 'local-delivery',
        'Evri'                => 'evri',   // <-- add your new mapping here
    ];
```

---

## SVG icon design guidelines

| Property | Recommended value |
|----------|-------------------|
| `viewBox` | `0 0 64 64` |
| Canvas size | 64 × 64 |
| Corner radius | `rx="10"` on background rect |
| Display size | 56px in list view, 72px in order view |

**Design approach:**
- Use a solid coloured rounded-square background (`<rect width="64" height="64" rx="10" fill="#BRAND_COLOUR"/>`)
- Place white shapes, text, or paths on top
- Keep it simple — icons scale up from a 64×64 canvas, so avoid very fine detail
- Avoid transparent backgrounds — the icons appear on both white and dark backgrounds

**Example — text-based icon template:**
```xml
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
  <rect width="64" height="64" rx="10" fill="#YOUR_BRAND_COLOUR"/>
  <text x="32" y="43" font-family="Arial,Helvetica,sans-serif"
        font-weight="900" font-size="20" fill="white"
        text-anchor="middle">ABC</text>
</svg>
```

**Example — shape-based icon template:**
```xml
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
  <rect width="64" height="64" rx="10" fill="#YOUR_BRAND_COLOUR"/>
  <!-- Add white shapes below -->
  <circle cx="32" cy="32" r="16" fill="white"/>
</svg>
```

---

## Existing icon brand colours for reference

| Courier | Background | Text / foreground |
|---------|-----------|-------------------|
| Royal Mail | `#E2001A` (red) | White |
| DPD | `#414042` (charcoal) | `#DC0032` (red) |
| DX | `#00305E` (navy) | `#F7A800` (amber) |
| Evri | `#6C2DC7` (purple) | White |
| Yodel | `#FF6600` (orange) | White |
| Customer Collection | `#6B7280` (grey) | White |
| Local Delivery | `#10B981` (green) | White |