# FAL Photo Browser

A TYPO3 extension for searching and importing stock photos directly in the TYPO3 backend.

**Powered by [Unsplash](https://unsplash.com)**

![Photo search results in the TYPO3 backend](https://raw.githubusercontent.com/dkd-dobberkau/fal-photo-browser/main/Resources/Public/Screenshots/photo-search.jpg)

## Features

- **Backend Module**: Dedicated module under "Media" for browsing and importing photos
- **Advanced Search**: Filter by text, orientation (landscape, portrait, square), and color
- **Local Import**: Downloads images to your fileadmin for GDPR compliance and performance
- **Automatic Metadata**: Populates title, description, and alt text, and photographer info, plus copyright and source if `EXT:filemetadata` is installed
- **Download Tracking**: Complies with Unsplash API guidelines by tracking downloads
- **Custom Metadata Fields**: Stores Unsplash photo ID, URL, and photographer name and URL for reference
- **AI Photo Assistant (optional)**: Describe the photo you need in your own words and get matching search terms and filters

## Requirements

- TYPO3 v14.0+
- PHP 8.2+
- Unsplash API Access Key ([Get one here](https://unsplash.com/developers))
- For the optional Photo Assistant: [EXT:aim](https://packagist.org/packages/b13/aim) with a configured provider, or an Anthropic API key ([Get one here](https://console.anthropic.com/))

## Installation

### Via Composer (recommended)

```bash
composer require dkd-dobberkau/fal-photo-browser
```

### Manual Installation

1. Download the extension
2. Place it in `packages/dkd_fal_photo_browser/`
3. Add the path repository to your `composer.json`:

```json
{
    "repositories": [
        {
            "type": "path",
            "url": "packages/*"
        }
    ]
}
```

4. Run `composer require dkd-dobberkau/fal-photo-browser:@dev`

### Activate Extension

```bash
vendor/bin/typo3 extension:setup --extension=dkd_fal_photo_browser
```

## Configuration

### API Key Setup

Set the `UNSPLASH_ACCESS_KEY` environment variable with your Unsplash API key.

#### DDEV

Add to `.ddev/config.yaml`:

```yaml
web_environment:
  - UNSPLASH_ACCESS_KEY=your_access_key_here
```

#### Apache/Nginx

```apache
SetEnv UNSPLASH_ACCESS_KEY your_access_key_here
```

```nginx
fastcgi_param UNSPLASH_ACCESS_KEY your_access_key_here;
```

#### Docker

```yaml
environment:
  - UNSPLASH_ACCESS_KEY=your_access_key_here
```

### Photo Assistant (optional)

The Photo Assistant can run through `EXT:aim` or call the Claude API directly. If `EXT:aim` is installed and has an enabled provider with conversation support, the assistant uses it. Otherwise it falls back to the Claude API. The choice applies to the whole installation: if `EXT:aim` denies a user or fails, the request fails and does not fall back.

#### With EXT:aim

Requires `b13/aim` 0.5.1 or newer and a Symfony AI bridge for your provider, for example:

```bash
composer require b13/aim:^0.5.1 symfony/ai-platform:^0.15 symfony/ai-anthropic-platform:^0.15
```

Then create a provider in the AiM backend module. API key, model, and request logging are managed there. Tested with `claude-sonnet-5-5`. EXT:aim states that it is tested up to Symfony AI 0.11, which does not know this model yet, so use `symfony/ai-platform:^0.11` if you prefer `claude-sonnet-5` or older.

#### With an Anthropic API key

Set the `ANTHROPIC_API_KEY` environment variable the same way as `UNSPLASH_ACCESS_KEY` above:

```yaml
web_environment:
  - ANTHROPIC_API_KEY=your_api_key_here
```

Photo search and import work without this key.

### Content Security Policy

The extension automatically registers CSP rules to allow loading thumbnail images from `images.unsplash.com` in the backend.

## Usage

1. Navigate to **Media > Photo Browser** in the TYPO3 backend
2. Enter a search term (e.g., "mountains", "office", "technology")
3. Optionally filter by orientation or color
4. Click **Import** on any photo to download it

### Photo Assistant

If the Photo Assistant is enabled, click **Photo Assistant** and describe what you need instead of searching by keyword, for example "a cozy café in the morning". The assistant replies in your language, creates English search terms, suggests orientation and color filters, and offers follow-up ideas to refine the search.

![The Photo Assistant suggesting search terms and filters](https://raw.githubusercontent.com/dkd-dobberkau/fal-photo-browser/main/Resources/Public/Screenshots/photo-assistant.jpg)

### Imported Images

Imported images are stored in `fileadmin/unsplash/YYYY/MM/` with full metadata including:

- Title and description
- Alt text
- Photographer name and URL
- Original Unsplash URL

If the TYPO3 system extension `EXT:filemetadata` (`typo3/cms-filemetadata`) is installed, the creator, copyright notice, and source fields are filled as well.

## File Structure

```
dkd_fal_photo_browser/
├── Classes/
│   ├── Controller/
│   │   └── PhotoBrowserController.php
│   ├── Domain/
│   │   └── Dto/
│   │       └── UnsplashPhoto.php
│   └── Service/
│       ├── FileImportService.php
│       └── UnsplashApiService.php
├── Configuration/
│   ├── Backend/
│   │   ├── AjaxRoutes.php
│   │   └── Modules.php
│   ├── ContentSecurityPolicies.php
│   ├── Icons.php
│   ├── Services.yaml
│   └── TCA/
│       └── Overrides/
│           └── sys_file_metadata.php
├── Resources/
│   ├── Private/
│   │   ├── Language/
│   │   │   └── locallang_mod.xlf
│   │   └── Templates/
│   │       └── Backend/
│   │           └── Index.html
│   └── Public/
│       ├── Css/
│       │   └── backend.css
│       ├── Icons/
│       │   └── module-falphotobrowser.svg
│       └── JavaScript/
│           └── photo-browser.js
├── composer.json
├── ext_emconf.php
└── ext_tables.sql
```

## Metadata Fields

The extension adds custom fields to `sys_file_metadata`:

| Field | Description |
|-------|-------------|
| `unsplash_photo_id` | Original Unsplash photo ID |
| `unsplash_photo_url` | Link to photo on Unsplash |
| `unsplash_photographer_name` | Photographer's name |
| `unsplash_photographer_url` | Link to photographer's profile |

These fields appear in a dedicated "Unsplash" tab when editing file metadata.

![The Unsplash tab in the file metadata form](https://raw.githubusercontent.com/dkd-dobberkau/fal-photo-browser/main/Resources/Public/Screenshots/metadata-unsplash-tab.jpg)

## API Compliance

This extension follows [Unsplash API Guidelines](https://help.unsplash.com/en/articles/2511245-unsplash-api-guidelines):

- Downloads are tracked via the API (required)
- Photographer attribution is stored in metadata
- "Powered by Unsplash" attribution in the UI
- Images are hotlink-free (downloaded locally)

## Data Protection

The Photo Assistant sends the messages you type, including the earlier messages of the conversation, to the [Anthropic API](https://www.anthropic.com/) or, with `EXT:aim`, to the provider configured there. The search terms it creates are sent to the Unsplash API. Do not enter personal or confidential data in the chat, and check whether your organization needs a data processing agreement before you enable it.

If neither is set up, no chat data leaves your installation.

## Support

Please report bugs and feature requests in the [GitHub issue tracker](https://github.com/dkd-dobberkau/fal-photo-browser/issues).

## License

GPL-2.0-or-later

## Credits

- Photos provided by [Unsplash](https://unsplash.com)
- Photo Assistant powered by [Claude](https://www.anthropic.com/claude)
- Built for TYPO3 CMS