# PHP Array Parameters in URLs

The Cineamo API uses PHP's bracket notation for array parameters in URLs.

## What Are PHP Array Parameters?

PHP uses square brackets `[]` in URL parameters to indicate arrays. When you see a parameter like `embed[]` or `cinemaIds[]`, you can pass multiple values.

```bash
# Single value - NO brackets needed
?contentId=123

# Multiple values - brackets required
?cinemaIds[]=1&cinemaIds[]=2&cinemaIds[]=3
```

---

## 🎯 Why Brackets?

Brackets tell PHP to treat the parameter as an array on the server side:

```
URL: ?ids[]=1&ids[]=2&ids[]=3
PHP receives: [1, 2, 3]

URL: ?ids=1  (no brackets)
PHP receives: "1"  (String, not array!)
```

---

## 📝 Common Examples

### Embed Multiple Resources

```bash
curl "https://api.cineamo.com/cinemas/123/future-showings?embed[]=cinema&embed[]=content&embed[]=cinemaRoom" \
  -H "Authorization: Bearer token"
```

### Filter by Multiple IDs

```bash
curl "https://api.cineamo.com/showings?cinemaIds[]=1&cinemaIds[]=2&cinemaIds[]=5" \
  -H "Authorization: Bearer token"
```

---

## 💻 Building URLs

Most HTTP clients handle this automatically:

```javascript
const params = new URLSearchParams();
params.append('embed[]', 'cinema');
params.append('embed[]', 'content');

const url = `https://api.cineamo.com/showings?${params.toString()}`;
```

**Note**: Brackets may be URL-encoded as `%5B` and `%5D` - both work with PHP.

---

## 🚨 Common Mistakes

### ❌ Forgetting Brackets

```bash
# Wrong - only last value used
?cinemaIds=1&cinemaIds=2

# Correct - array with all values
?cinemaIds[]=1&cinemaIds[]=2
```

### ❌ Adding Indices

```bash
# Wrong - unnecessary
?embed[0]=cinema&embed[1]=content

# Correct - let PHP auto-index
?embed[]=cinema&embed[]=content
```

---

## 📋 Quick Reference

| Parameter | Single Value | Multiple Values |
|-----------|--------------|-----------------|
| `contentId` | `?contentId=123` | N/A (single only) |
| `embed` | `?embed[]=cinema` | `?embed[]=cinema&embed[]=content` |
| `cinemaIds` | `?cinemaIds[]=1` | `?cinemaIds[]=1&cinemaIds[]=2` |
| `showingTagIds` | `?showingTagIds[]=5` | `?showingTagIds[]=5&showingTagIds[]=8` |

### When to Use Brackets

- ✅ **Use brackets** for `embed[]`, `cinemaIds[]`, `showingTagIds[]`, etc.
- ❌ **Don't use brackets** for `contentId`, `cinemaId`, `page`, `per_page`

---

## 📚 See Also

- [HAL Responses](/hal-responses) - Understanding response format
- [Fetching Showtimes](/showtimes) - Practical examples
- [API Reference](/api) - Complete parameter list