nanoPhotosProvider2 - the easiest and fastest way to publish your self-hosted photos to nanogallery2.


PHP application for publishing your photos from your web server.

Automatic generation of responsive thumbnails

Blurred image preview during thumbnail download.

Compatible with all nanogallery2 layouts.

grid layout

fixed width and height

justified layout

fixed height, variable width

cascading layout

fixed width, variable height

mosaic layout

pattern based layout

Supports photo albums.

Easy to install and maintain - no database, only flat files.

Add-on for nanogallery2

Get new release alerts by following   follow @nanostudio_org

nanoPhotosProvider2 usage

Step 1: installation

On your webserver:
- create a folder named nano_photos_provider2
- in this folder:
  • copy the files:
    • nano_photos_provider2.php
    • nano_photos_provider2.json.class.php
    • nano_photos_provider2.cfg
    • nano_photos_provider2.encoding.php
  • create a folder named nano_photos_content
    • copy your photos there
    • you can organize your photos in folders (= albums)

Step 2: configure your HTML page

  • The page can be located anywhere on your webserver.
  • Install and configure nanogallery2 (see
  • Configure the call to the plugin:
    • Use the specific parameters: kind and dataProvider
    • kind: set value to 'nano_photos_provider2'
    • dataProvider: URL to the nano_photos_provider2.php file installed in step 1

            jQuery(document).ready(function () {
                thumbnailWidth:   'auto',
                thumbnailHeight:  150,
                kind:             'nano_photos_provider2',
                dataProvider:     '',
                locationHash:     false

Step 3: test your page to see the result

Settings and configuration

Content management
You can add images and folders, or rename them, in your content folder.
Please note that the generated thumbnails are never purged, so you may delete the _thumbnails folders to force a new generation.

Title, description, tags
- Title
File names and folder names are used as title in nanogallery2.
The special caracter underscore '_' will be replaced by a white space.

- Description
A description can be defined in the file names or in the folder names.
Use '$$' to separate title and description. Example: 'Berlin$$Brandenburger_Gate.jpg'

- Metadata files
One metadata file can be optionally defined to store additional photo information.
It's an alternative solution for defining title and description.
Tags/keywords are defined in this file.

The metadate file has the same name as the image, with the extension '.txt'.
File content syntax:

        title= this is my title
        description= this is my descritption
        tags=tag1 tag2 tag3

- Album cover image
By default, the first image found in a folder will be used for the album cover image.
The cover image can be specified by adding a leading @@@@@ to the filename of the image to be used.

- IDs
Note that filenames and folder names are used as IDs. So if you rename an image or folder, previous used links to the renamed element will no longer work.

- Supported image formats

- Custom configuration
Custom settings are defined in nano_photos_provider2.cfg

section option default value description
fileExtensions "jpg|jpeg|png|gif" Supported file extensions (separtor is |)
contentFolder "nano_photos_content" Folder where albums and images are stored
sortOrder "asc" Filename sort order (asc or desc), ctime sort order (asc_ctime, desc_ctime), mtime sort order (asc_mtime, desc_mtime), sort using prefix (see sortPrefixSeparator for further details)(asc_prefix, desc_prefix)
sortOrderAlbum "" Album sort order, if not specified will sort using the same order specified in sortOrder
sortPrefixSeparator "==" Separator between sort prefix and the title. Everything before the separator (the "Prefix") and the separator will be excluded from the title. The Prefix can be used to sort the albums or files. Helpful if you want to sort by date, but don't want the date to appear in the title such as: 2012-05015==Some Title
titleDescSeparator "$$" Separator between title and description in the filename or foldername
albumCoverDetector "@@@@@" Leading sequence in the filename of the image to be used as an album cover
ignoreDetector "_hidden" Ignore photos/albums (folders) containing this sequence in their name
maxSize* 1900 max. width/height of the displayed images
jpegQuality* 85 JPEG quality of the images
jpegQuality* 85 JPEG quality for the thumbnails
blurredImageQuality* 3 Quality of the blurred images (higher is better but slower)
allowedSizeValues "" List of allowed values for thumbnail image sizes (separtor is |)
Values should be the same as in your nanogallery2 settings.
Example: allowedSizeValues = "100|150|300|auto"
allowOrigins "*" List of allowed domain (CORS)
Example: allowOrigins = ""
unlimited false Set to true to disable PHP memory management. May be useful for large images.
Use with caution!
*: after changing any of these values, please delete all _thumbnails folders to refresh the cached data.


nanogallery2 >= v1.4
PHP > v5.3 with GD-Library and EXIF-Library enabled
PHP 8 is not supported

Tips and tricks

- Perfomances
Lowres images, thumbnails and blurred images are generated on first request and then cached on disk.
On first use, or after adding a large amount of new images, you may encounter delays, timeouts or error messages (depending on the performances of your web server) -> reload the page until you don't get any error. Generated data will then be cached, for faster access.

Due to browser security features, dataProvider can not point to localhost, or similar.
Possible workaround:
  • configure your server to allow CORS (see,
  • or install a browser extension to disable CORS checking.

Generation of thumbnails could be missused to satured the server disk space.
It's highly recommanded to limit accepted values for thumbnail sizes in the nano_photos_provider2.cfg configuration file.

- Limitations
The nanogallery2 option locationHash should NOT be enabled if albums have more than 2 levels.


nanoPhotosProvider2 is open source and licensed under GPLv3 license.


Need help using nanoPhotosProvider2?

Start by reading the documentation .
Questions, issues and bugs should be reported on Github.