PageBox

This Site The Web for

Support     Home     Word

PageBox for PHP customization

Table of content

Deliveries Repository archive.inc subcriber.php select.php asubscriber.php download.php publisher.php admin.php environment.php audit.php cleanup.php batch.php RepoQuery.php RepoQueryClient.php PageBox update.php environment.php pagebox.inc Query.php QueryRelay.php QueryClient.php log.php

You can download PageBox for PHP in:

• Zip format

• Tar compressed with gzip

• Tar compressed with compress

PageBox for PHP repository is made of the following files:

PageBox for PHP is made of the following files:

archive.inc contains two core classes:

• ArchiveRep. ArchiveRep maintains an associative array of the presentations managed by a repository. It has two methods, add to add an presentation to the repository and delete to remove a presentation from the repository.

• RepoSubs. RepoSubs maintains an associative array of the repository subscribers. It has six methods, subscribe to add a subscriber to the repository and unsubscribe to remove a subscriber from the repository, asubscribe to add an archive subscriber to the repository and unasubscribe to remove an archive subscriber from the repository, add to add a presentation to an archive subscriber, delete to remove a presentation from an archive subscriber.

A subscriber is described by a Subscriber object. The Subscriber object contains an associative array of the presentations deployed or pending for deployment.

When a new presentation is added, it is deployed on every subscriber and added to the Subscriber object.

When a new PageBox subscribes, it receives all presentations defined in ArchiveRep.

Presentations are not automatically added to archive subscribers but when an archive subscriber has subscribed a presentation, it receives presentation updates.

Both ArchiveRep and RepoSubs are serialized and restored:

• save_archives serializes the repository ArchiveRep in archives.rep

• restore_archives restores the repository ArchiveRep from archives.rep

• save_subscribers serializes the repository RepoSubs in subscribers.rep

• restore_subscribers restores the repository RepoSubs from subscribers.rep

To deploy a presentation a deploy function is invoked. It uses HTTP GET to query pagebox/update.php for the installation of a new presentation.

To undeploy a presentation an undeploy function is invoked. It uses HTTP GET to query pagebox/update.php for the deletion of a presentation.

Note:

archives.rep and subscribers.rep are created and managed by archive.inc.

PHP serialization is fairly readable. However avoid modifying these files by hand.

archive.inc implements:

• The locking mechanism through lock and unlock functions

• Logging through the audit function

• Deploy and undeploy retry through the cleanup function

cleanup is described in admin.php and cleanup.php sections.

The repository locking mechanism uses a file, lock.rep.

• When it contains 1, the repository is locked and lock returns false.

• When it contains 0, the repository is unlocked.

We use flock to lock the access to lock.rep.

The mechanism is portable and simple but race conditions are possible when PHP is configured as a module.

subscriber.php manages a form in GET mode that

• Lists the Repository subscribers

• Allows adding and removing subscribers

subscriber.php provides two buttons to remove subscribers Unsub/Unsubscribe and Force.

Force allows removing a PageBox that doesn!#8217;t exist (anymore) whereas Unsubscribe keeps the subscriber in "pending unsubscribe" state. In that state the subscriber doesn!#8217;t receive new archives.

select.php manages a form in GET mode that

• Lists the Repository archive subscribers

• Allows adding and removing archive subscribers

select.php provides two buttons to remove archive subscribers Unsub/Unsubscribe and Force.

Force allows removing a PageBox that doesn!#8217;t exist (anymore) whereas Unsubscribe keeps the archive subscriber in "pending unsubscribe" state. In that state the subscriber doesn!#8217;t receive archive updates.

select.php provides an Archives button to select archives. When you click Archives, a new window is created to display asubscriber.php.

asubscriber.php manages a form in GET mode that

• Lists the Repository archives

• Allows selecting subscribed archives

When an archive subscriber has subscribed a presentation, the archive checkbox is set.

You check an archive checkbox to subscribe the presentation (then the presentation is deployed on the subscriber PageBox).

You uncheck an archive checkbox to unsubscribe the presentation (then the presentation is undeployed on the subscriber PageBox).

The actual deploy/undeploy takes place when you click on the Refresh button.

download.php allows downloading presentations from Repositories without subscription:

When the presentation is updated, it is not deployed on the download site.

The download site doesn!#8217;t need a PageBox.

download.php displays the Repository meta data:

• The publisher (owner) of the presentation

• The documentation posted by the owner

Therefore it should be preferred to directory browsing for Repository download.

publisher.php manages a form in POST mode that

• Lists the uploaded presentations

• Allows uploading and removing presentations.

If a users.rep file exists, it should contain a list of allowed publishers, for instance:

Then:

1. publisher.php only accepts queries from users defined in users.rep

2. In case of publication, publisher.php registers the user as the owner of the presentation

3. publisher.php only displays archives belonging to the user

4. A user B cannot publish a presentation with the same name as a presentation previously published by a user A

5. update.php displays the owner of deployed archives

When users.rep is not defined, there is no security check, no publication isolation and no audit.

For production, you should define users.rep and implement security as described in the Security guide.

publisher.php uses POST method upload as defined in RFC 1867.

It moves uploaded presentations from a directory defined in upload.rep to a download directory.

upload.rep should contain the directory where move_uploaded_file($HTTP_POST_FILES["arch"]["tmp_name"], "myPresentation")

stores myPresentation.

In case of Apache with PHP module, it is the Apache directory. For instance on Win 32, if Apache was installed on D drive:

Note:

If move_uploaded_file($HTTP_POST_FILES["arch"]["tmp_name"], "myPresentation") stores myPresentation in the repository directory, you don!#8217;t need to define upload.rep.

Beside the presentation location, publisher.php allows specifying the URL of the presentation documentation. This URL is stored in archives.rep and sent to PageBoxes.

To delete archives, publisher.php provides two buttons, Delete and Force.

In both cases publisher.php send an undeploy(presentation) to all subscribers and removes the presentation file from the repository.

If the undeploy succeeds, the presentation is removed from the archive list of the subscriber.

If the undeploy fails for one subscriber:

• The presentation is removed from the archive list of the subscriber in case of Force

• The presentation is kept in the archive list of the subscriber in case of Delete

admin.php manages a form in GET mode that:

• Lists the uploaded presentations

• Allows removing presentations.

publisher.php is a Presentation publisher tool.

admin.php is the tool of the repository administrator.

It displays all published presentations.

If adminUser.rep is defined it contains the Repository administrator userid, for instance:

Then admin.php only accepts queries coming from the Repository administrator.

To delete archives, admin.php provides two buttons, Delete and Force.

In both cases admin.php send an undeploy(presentation) to all subscribers and removes the presentation file from the repository.

If the undeploy succeeds, the presentation is removed from the archive list of the subscriber.

If the undeploy fails for one subscriber:

• The presentation is removed from the archive list of the subscriber in case of Force

• The presentation is kept in the archive list of the subscriber in case of Delete

environment.php displays:

• The Repository Web server environment variables

• The PHP configuration

• The PHP environment variables

environment.php uses phpinfo().

audit.php displays for each Repository event:

• The event date and time

• The host that triggered the event

• The user that triggered the event

• The event and its status

A Repository event can be:

• A page query

• A subscription, a publication...

Note:

1. Audit is implemented in archive.inc!#8217;s lock and audit functions.

2. Audit events are stored in audit.html

audit.php provides a Clear button to remove the audit.html file.

If adminUser.rep is defined it contains the Repository administrator userid, for instance:

Then audit.php only accepts queries coming from the Repository administrator.

A PageBox can be unavailable when a deploy or undeploy is issued.

In that case the deployment or undeployment remains in pending state.

The archive.inc!#8217;s cleanup function retries the deployment/undeployment of archives in pending state.

It can be invoked through the Cleanup button of admin.php.

To call cleanup automatically, you can use a batch command cleanup.php.

cleanup.php expects a single parameter, the download location (where PageBoxes download presentations from the repository).

On Unix, cleanup.php should be defined with execution right (chmod +x cleanup.php).

We wrote a example of batch file for Windows, cleanup.bat:

You probably need to change this data:

1. E: is the drive where the repository is installed.

2. \Program Files\Apache Group\Apache\htdocs\repository is the repository path.

3. E:\PHP406\php.exe is the php.exe path.

4. localhost:2080/download is the download location.

Both on Unix and Windows you should write the output of cleanup.php in batch.html in the Repository directory to be able to display it with batch.php.

batch.php displays the content of batch.html.

It also allows deleting batch.html with the Clear button.

If adminUser.rep is defined it contains the Repository administrator userid, for instance:

Then batch.php only accepts queries coming from the Repository administrator.

RepoQuery is a SOAP Web service designed to be used in combination with the Query Web service to allow distributed applications to retrieve their peers.

An example of such Web applications is available for .NET, Reservation.

The figure below shows a typical use case:

1. The distributed application uses the Query Web service to retrieve the list of the subscribers. Technically the PageBox Query Web service invokes the RepoQuery Web service of the repository.

2. Then the distributed application (here Reservation) calls Web services (here Location) on its peer instances. Typically these Web services answer questions: Where? What? Is the good available? Which price? Which data do you own?

RepoQuery requires PEAR, which is distributed with recent versions of PHP and PEAR SOAP.

See the installation guide for more information about PEAR SOAP.

RepoQuery uses archive.inc to retrieve the subscribers to the archive from the ArchiveRep and RepoSubs objects.

Distributed applications should only know their managing PageBox and call Query. They should not call RepoQuery.

RepoQueryClient is a server page that invokes the RepoQuery Web service to retrieve the subscribers to an archive. Like RepoQuery.php, RepoQueryClient.php is distributed in a repoQuery directory because RepoQuery and RepoQueryClient typically don!#8217;t require authentication and authorization.

RepoQueryClient requires PEAR, which is distributed with recent versions of PHP and PEAR SOAP.

See the installation guide for more information about PEAR SOAP.

update.php manages a form in GET mode that

1. Lists the deployed presentations

2. Allows deploying and undeploying presentations.

update.php is invoked by deploy and undeploy functions of archive.inc.

A deploy query has a format:

pagebox_update.php_url?download=presentation&from=repository_download_url

&owner=publisher_userid&doc=documentation_URL&size=presentation_size

&date=presentation_last_modified_date

An undeploy query has a format:

pagebox_update.php_url?delete=presentation

When update.php receives a deploy request it:

1. Downloads the presentation from the download location

2. Inflates the presentation according to the content of inflate.pb

3. Records the presentation in the PbArchives.object

When update.php receives a deploy request it:

1. Removes the presentation from the PbArchives.object

2. Removes the inflated presentation according to the content of delete.pb

3. Delete the downloaded presentation

For every presentation extension inflate.pb describes the command run to inflate the presentation. For instance:

In that case update.php runs the command inflate.bat presentation_without_extension.

inflate.bat can be written like this:

Only presentations whose extension is listed in inflate.pb are installed.

If you don!#8217;t need to run a command to post process the presentation (for instance a Jar file), write:

Extension : -. For instance:

For every presentation extension delete.pb describes the command run to remove the presentation. For instance:

In that case update.php runs the command delete.bat presentation_without_extension.

delete.bat can be written like this:

environment.php displays:

• The Repository Web server environment variables

• The PHP configuration

• The PHP environment variables

environment.php uses phpinfo().

pagebox.inc contains a PbArchives class. PbArchives maintains an associative array of the presentations deployed on the PageBox. It has two methods, add to add a presentation to the PageBox and delete to remove a presentation from the PageBox.

The PbArchives.object is serialized to and restored from pbarchive.pb file.

Note:

pbarchives.pb is created and managed by archive.inc.

PHP serialization is fairly readable. However avoid modifying this file by hand.

pagebox.inc also contains two functions:

1. pblog that writes log records in log.html and is called by Query.php, QueryClient.php and QueryRelay.php

2. repoQuery, which is the Query client code, invoked by QueryRelay.php. If you have a PEAR SOAP version that supports combining a SOAP client and server in the same module you can change the Query code as explained in the comments in order to use repoQuery

Query.php is the PageBox Web service. It returns the list of the subscribers to an archive.

To retrieve this list, it calls the QueryRelay.php server page.

If you have a PEAR SOAP version that supports combining a SOAP client and server in the same module you can change the Query code as explained in the comments in order to use repoQuery.

Query requires PEAR, which is distributed with recent versions of PHP and PEAR SOAP.

See the installation guide for more information about PEAR SOAP.

QueryRelay.php is a server page that invokes the RepoQuery Web service using the repoQuery function of pagebox.inc. Then it returns the list of the subscribers in a format:

This format is suitable when QueryRelay.php is invoked by a program such as Query.php. You easily can change it to return the subscriber list in XML.

QueryRelay.php requires PEAR, which is distributed with recent versions of PHP and PEAR SOAP.

See the installation guide for more information about PEAR SOAP.

QueryClient is a server page that invokes the Query Web service to retrieve and display the subscribers to an archive.

QueryClient requires PEAR, which is distributed with recent versions of PHP and PEAR SOAP.

See the installation guide for more information about PEAR SOAP.

log.php displays for each PageBox event:

• The event date and time

• The event and its status

Note:

1. log is implemented in pagebox.inc!#8217;s pblog function

2. log events are stored in log.html

log.php provides a Clear button to remove the log.html file.

Contact:support@pagebox.net
©2001-2004 Alexis Grandemange. Last modified .