This package contains a simple embeddable gallery that can be integrated into a web application. It supports the following features:
- Displaying a collection of albums, collections of pictures
- A gallery's content can be managed by users
- Storing GIF, JPEG and PNG images
- Automatic scaling of images
- Embedded HTML editor for managing descriptions
- Bulk importer
- Translatable into a language of choice
- Integratable into the
php-sbeditor
,php-sblayout
andphp-sbdata
frameworks
The gallery is built on top of the functionality provided by the following packages:
This package can be embedded in any PHP project by using
PHP composer. Add the following items to your
project's composer.json
file:
{
"repositories": [
{
"type": "git",
"url": "https://github.com/svanderburg/php-sbgallery.git"
}
],
"require": {
"svanderburg/php-sbgallery": "@dev",
}
}
and run:
$ composer install
When it is desired to modify the code or run the examples inside this repository, the development dependencies must be installed by opening the base directory and running:
$ composer install
There are two ways to use the functionality exposed by this package. It can be controlled directly by using the low-level API requiring the user to manually compose object instances representing parts of the gallery, displaying the corresponding views and implement controllers to modify the gallery's state.
Alternatively, this package provides a high level API exposing Page
instances
that can be integrated with the php-sbcrud
framework. When using the CRUD API
you only need to compose a configuration once. The corresponding pages that
provide all functionality are generated automatically.
In addition to embedding a gallery components into pages or pages into an
application, a gallery can also be integrated into a HTML editor managed by the
php-sbeditor
framework and optionally into forms managed by php-sbdata
.
With this functionality users can automatically insert pictures from the gallery
into HTML code generated by the editor.
The low-level API provides direct control over the gallery's state.
We can create a gallery, that displays an overview of available albums with a thumbnail, as follows:
use SBGallery\Model\Gallery;
use SBGallery\Model\Settings\GallerySettings;
use SBGallery\Model\Settings\URLGenerator\SimpleGalleryURLGenerator;
$dbh = new PDO("mysql:host=localhost;dbname=gallery", "user", "password", array(
PDO::ATTR_PERSISTENT => true
));
GallerySettings $settings = new GallerySettings(new SimpleGalleryURLGenerator(), // An object that defines how URLs to the sub pages should be generated
"gallery", // The directory in which the gallery's images reside
160, 160, // The maximum dimensions of a thumbnail
1280, 1280, // The maximum dimensions of a picture
0666 // The permissions of picture files in the gallery directory
0777 // The permissions of directories in the gallery directory
);
Gallery $gallery = new Gallery($dbh, $settings);
The above code snippet sets up a database connection and configures a gallery with the following settings:
- It uses a
URLGenerator
object to generate URLs that link to albums, pictures and their corresponding operation pages. TheSimpleGalleryURLGenerator
implements a URL convention in which the gallery is managed by thegallery.php
page, albums with thealbum.php
page and pictures by thepicture.php
page. The pages use GET parameters to determine which album and picture have been requested. - It uses the
gallery/
folder as the base directory of all images - The maximum dimensions of a thumbnail are 160x160 pixels
- The maximum dimensions of a picture are 1280x1280 pixels
- The file permissions of the picture files are read, write support for the owner, group and others
- The directory permissions of a picture directory are read, write, execute support for the owner, group and others
There are more configuration properties supported beyond the ones shown in the example. Consult the API documentation for more information.
We can render the gallery in read mode with the following function call:
\SBGallery\View\HTML\displayGallery($gallery);
Rendering the gallery in write mode, in which the user can modify its contents, can be done with the following funcion call:
\SBGallery\View\HTML\displayEditableGallery($gallery);
The low level API implements a variety of album operations.
We can query an album from the gallery as follows:
$album = $gallery->queryAlbum("myalbum");
The above method invocation queries the album with the identifier: myalbum
.
If the album does not exists, the method returns an AlbumNotFoundException
.
We can create a new album as follows:
$album = $gallery->newAlbum();
The above method call creates a new album that inherits the configuration settings from the gallery.
We can import album settings from the request variables and check its validity as follows:
$album->importValues($_REQUEST);
$album->checkFields();
$valid = $album->checkValid(); // Returns true if the album properties are valid, otherwise false
We can insert an album into the database with the following method call:
$gallery->insertAlbum($album);
An existing album can be updated with the following method call:
$gallery->updateAlbum("myalbum", $updatedAlbum);
The above method call updates the album with identifier: myalbum
with the
properties of the $updatedAlbum
.
An album can be removed with the following method call:
$myGallery->removeAlbum("myalbum");
We can also upload multiple images into an album (albums will automatically adopt the image filename as a title and identifier) and scale it down according to the gallery's specifications with the following method invocaion:
$album->insertMultiplePictures("Image");
The parameter specifies the name of the form field that facilitates the multiple file upload.
The following methods can be used to move an album left or right in the gallery:
$result = $myGallery->moveLeftAlbum("myalbum");
$result = $myGallery->moveRightAlbum("myalbum");
The method call returns true
if the album was moved, and false
if it did
not. When an album has reached the beginning or end in the gallery these methods
return false
.
An album can be rendered in read mode with the following function call:
\SBGallery\View\HTML\displayAlbum($album);
We can also render an album in write mode, in which the user can change the properties of the album, and adjust the pictures inside it:
\SBGallery\View\HTML\displayEditableAlbum($album);
As shown earlier, the album editor can also upload multiple pictures at the same time. To render the form that provides the input fields, we can do the following function call:
$picturesUploader = $album->constructPicturesUploader();
\SBGallery\View\HTML\displayPicturesUploader($picturesUploader);
The low-level API makes it also possible to directly manage pictures.
We can query a picture from an album as follows:
$picture = $album->queryPicture("mypicture");
The above method invocation queries the album with the identifier: mypicture
.
If the album does not exists, the method returns an PictureNotFoundException
.
We can create a new picture as follows:
$picture = $album->newPicture();
The above method call creates a new picture that inherits the configuration settings from the album.
We can import picture settings from the request variables and check its validity as follows:
$picture->importValues($_REQUEST);
$picture->checkFields();
$valid = $picture->checkValid(); // Returns true if the picture is valid, otherwise false
We can insert a picture into the database with the following function call:
$album->insertPicture($picture);
In addition to inserting the picture into the database, it will also automatically upload a user provided image and scales it according to the gallery's specifications.
An existing picture can be updated with the following method call:
$album->updatePicture("mypicture", $updatedPicture);
The above method call updates the picture with identifier: mypicture
with the
properties of the $updatedPicture
.
In addition, it will also automatically upload a user provided image and scales it according to the gallery's specifications.
A picture can be removed with the following method call:
$album->removePicture("mypicture");
The following methods can be used to move a picture left or right in the abum:
$album->moveLeftPicture("mypicture");
$album->moveRightPicture("mypicture")
The method call returns true
if the picture was moved, and false
if it did
not. When a picture has reached the beginning or end in the albums these methods
return false
.
To set a picture as a thumbnail for an album, we can use the following method call:
$album->setAsThumbnail("mypicture");
It is possible to add a picture to an album without an image. To clear an existing image in a picture we can use the following method call:
$album->clearPicture($_REQUEST["PICTURE_ID"]);
A picture, including navigation controls, can be rendered in read mode with the following function call:
\SBGallery\View\HTML\displayPicture($picture);
We can also render a picture in write mode, in which the user can change the properties of the picture:
\SBGallery\View\HTML\displayEditablePicture($picture);
The high-level API is an API that is built on top of the php-sblayout
and
php-sbcrud
frameworks. The idea is that you can easily embed a fully
functional gallery into an existing application (including authentication
checks) by composing GalleryPage
object and adding it to the Application
's
page structure.
First, we must construct our own permission checker that determines whether a user has write permissions:
use SBGallery\Model\GalleryPermissionChecker;
class MyGalleryPermissionChecker implements GalleryPermissionChecker
{
public function checkWritePermissions(): bool
{
return ($_COOKIE["Password"] === "secret");
}
}
In the above checker, you must implement your own password policy, such as integrating with a database or external authentication system.
Then we must construct a GalleryPage
instance that we can add to an
application's page structure. A GalleryPage
accepts many kinds of
configuration parameters including a permission checker.
A convenient way to compose an instance and keep the code clean, is to create a
sub class from GalleryPage
:
use PDO;
use SBGallery\Model\Gallery;
use SBGallery\Model\GalleryPermissionChecker;
use SBGallery\Model\Page\GalleryPage;
class MyGalleryPage extends GalleryPage
{
public function __construct(PDO $dbh)
{
parent::__construct($dbh, new GalleryPageSettings("gallery"), new MyGalleryPermissionChecker());
}
}
The above sub class: MyGalleryPage
defines a new constructor that composes a
GalleryPage
with desired configuration settings, such as:
- The database connection handler:
$dbh
- Various gallery page settings. The base directory of the gallery images is:
gallery/
- The gallery permission checker that we have defined earlier.
There are many kinds of gallery settings that can be configured, such as the
icons and labels. Consult the API documentation for the GalleryPage
and
GalleryPageSettings
classes for more information.
We can add a page instance of our sub class to the application layout as follows:
use SBLayout\Model\Application;
use SBLayout\Model\Page\HiddenStaticContentPage;
use SBLayout\Model\Page\PageAlias;
use SBLayout\Model\Page\StaticContentPage;
use SBLayout\Model\Page\Content\Contents;
use SBLayout\Model\Section\ContentsSection;
use SBLayout\Model\Section\MenuSection;
use SBLayout\Model\Section\StaticSection;
$application = new Application(
/* Title */
"Gallery",
/* CSS stylesheets */
array("default.css"),
/* Sections */
array(
"header" => new StaticSection("header.php"),
"menu" => new MenuSection(0),
"contents" => new ContentsSection(true)
),
/* Pages */
new StaticContentPage("Home", new Contents("home.php"), array(
"400" => new HiddenStaticContentPage("Bad request", new Contents("error/400.php")),
"404" => new HiddenStaticContentPage("Page not found", new Contents("error/404.php")),
"home" => new PageAlias("Home", ""),
"gallery" => new MyGalleryPage()
))
);
Adding the page object to the application layout allows us to:
- Access the gallery through:
http://localhost/gallery
- Access each album through:
http://localhost/gallery/<albumId>
- Access each picture through:
http://localhost/gallery/<albumId>/<pictureId>
Because the high-level API is also using the php-sbcrud
framework, we can
access CRUD operations (other than reading) by appending a __operation
request
paramer, such as:
http://localhost/gallery/myalbum/mypicture?__operation=moveleft_picture
By invoking the above URL (and having met the appropriate authentication criteria) the picture will be moved left in the album.
In addition to using the high level API to embed the gallery as a sub application into an application layout, we can also expose albums as browseable sub pages from a menu.
By using albums as pages, we can use the gallery as a simple content manager allowing a user to dynamic construct sub pages of a web applications including the contents of the pages.
Instead of creating an instance of the GalleryPage
class, we must instantiate
the TraversableGalleryPage
class.
As with the previous example, for convenience, we can construct such a page with its configuration settings by creating a sub class:
use PDO;
use SBGallery\Model\Gallery;
use SBGallery\Model\GalleryPermissionChecker;
use SBGallery\Model\Page\TraversableGalleryPage;
class MyGalleryPage extends TraversableGalleryPage
{
public function __construct(PDO $dbh)
{
parent::__construct($dbh, new GalleryPageSettings("gallery"), new MyGalleryPermissionChecker());
}
}
Composing the application layout is done in exactly the same way as the previous example.
A gallery can also be embedded into a HTML editor implemented by the
php-sbeditor
framework allowing users to insert pictures from the gallery into
the text that he composes in the editor.
By invoking the displayHTMLEditorWithGallery()
function:
\SBGallery\View\HTML\displayHTMLEditorWithGallery("editor1", "contents", "picturepicker.php", "iframepage.html", "image");
we can directly generate a div
providing a textarea
and two iframe
s
showing the gallery and editor.
The corresponding div has an id: editor1
, the textarea field has the name:
contents
, the gallery iframe embeds the picturepicker.php
page and the
editor iframe embeds the iframepage.html
page. The editor's icons are stored
in the image/
sub folder.
The generated div
should be embedded inside a form
element.
We also have to create the picturepicker.php
page showing the embedded album
that integrates with a gallery object:
<?php
$myGallery = new MyGallery();
\SBGallery\View\HTML\displayPicturePickerPage($myGallery);
?>
As can be seen in the above example, the picturepicker.php
page can be
generated in a straight forward manner -- simply composing a gallery object and
invoking displayPicturePickerPage()
suffices.
This framework also provides a HTMLEditorWithGalleryField
class that can be
used to construct fields that can be added to a Form
managed by the
php-sbdata
framework:
use SBData\Model\Form;
use SBData\Model\Field\TextField;
use SBGallery\Model\Field\HTMLEditorWithGalleryField;
$form = new Form(array(
"title" => new TextField("Title", true),
"contents" => new HTMLEditorWithGalleryField("editor1", "Contents", "picturepicker.php", "iframepage.html", "image", true)
));
When displaying the above form as an editable form:
\SBData\View\HTML\displayEditableForm($form);
Then the corresponding field will be displayed as an HTML editor with embedded gallery (or a text area if JavaScript functionality is absent). The parameters to the HTML editor field constructor are similar to those of the view function shown in the previous section.
This package contains two examples in the example/
sub folder:
- The
lowlevel
folder contains an example using the low-level API. It provides a gallery, album, picture and multiple pictures upload page. - The
crud
folder contains an example using the high-level API. It provides a gallery with a useless authentication check (theview=1
GET parameter). Thecrud-translated
folder extends the previous example with a translated version the gallery to Dutch. - The
crud-paged
folder extends thecrud/
example with pagination support in which a fixed number of album and picture thumbnails are displayed per page - The
pages
folder contains an example of exposing albums as sub pages in the application layout so that parts of the web application content can be managed by end-users. - The
simpleeditor
folder contains a very basic example showing an HTML editor with embedded gallery. - The
formeditor
folder contains an example of an editor with gallery integrated into thephp-sbdata
framework, so that input can be automatically validated and presented. - The
formeditor-translated
folder extends the previous example with a translation to Dutch - The
formeditor-paged
example extends theformeditor
example with pagination support
This package includes API documentation that can be generated with Doxygen:
$ doxygen
The contents of this package is available under the Apache Software License version 2.0
The icons used in this project are borrowed from the Tango icon library. The icons are in the public domain.