Packages Tutorial

In this tutorial, we will introduce how Packages organize and write web application files to the file system, which can be accessed from a web browser.  Then we will create a basic PHP web app to view and manage the presidents database created in the Content Type Tutorial.

Packages

webCOMAND Packages are similar to webCOMAND Folders, in that they are typically used to organize a collection of related content in the repository.  However, Packages have an optional Namespace and will write File content to the file system upon approval by default.

More specifically, a Package can be assigned a Namespace like 'com_mywebsite_www' to write all File content within the Package to the following path in the file system.

/var/www/webcomand/files/packages/com_mywebsite_www/

webCOMAND will route web requests with a package namespace from the first path segment to an index.php file in the corresponding location in the file system.

In other words, if you create a PHP File with the Filename index.php in a Package with the namespace above, it will write the PHP File to:

/var/www/webcomand/files/packages/com_mywebsite_www/index.php

index.php will be processed, with the COMAND autoloader enabled, for any URL that begins with:

https://<account>.webcomand.com/com_mywebsite_www/

In addition, any files written to a subfolder named 'public' will be servered directly.  PHP files in the public folder will also be processed, with the COMAND autoloader enabled.  For example, if you create a PHP File with the Filename public/test.php, it will write the PHP File to:

/var/www/webcomand/files/packages/com_mywebsite_www/public/test.php

test.php will be processed, with the COMAND autoloader enabled, from the URL:

https://<account>.webcomand.com/com_mywebsite_www/test.php

This makes it easy to set up a web application with little effort.  A number of options are available to configure custom URLs and utilize various webCOMAND and third-party frameworks.

With these general concepts in mind, we will next build a simple PHP web application.

Create "Presidents Demo" Package

In webCOMAND, a web app can be created as a Package that contains all of the app's code and support files.  A package makes it easy to organize, access and share a collection of related files and objects.  So, the first thing we will do is create a new Package.

1. Launch the Content Manager (CMS) App.
2. In the folder tree on the left, expand and click: Bases / Presidents
3. Click the Add Content menu () and select "Package" in the drop-down.
4. Enter the Title "Presidents Demo"
5. Click the Package tab and enter a unique Namespace for our app, such as "com_presidentsdemo_www".  Reverse domain name notation is not required, but is a best practice to ensure unique package folder names and namespaces.
6. Click Approve.

Create "public/index.php" PHP File

Now that we have a package, we can add our first PHP web app file.

1. Click the Contents tab in our new "Presidents Demo" Package.
2. Click the New Menu () in the Contents field and select "PHP File" in the drop-down.
3. Enter the Filename "public/index.php".
4. Enter the Text:

   <?php
   // connect to the default comand repository
   $repo = \comand::repo();
   
   // list presidents
   $presidents = $repo->get('FROM President ORDER BY Number');
   echo('<ol>');
   foreach($presidents as $p) {
       echo('<li value="' . $p->Number . '">' .
        '<a href="edit.php?oid=' . $p->OID . '">' . $p->Name . '</a>' .
        '</li>');
   }
   echo('</ol>');

5. Click Approve and then Back.

Create "public/edit.php" PHP File

Now we can add the edit functionality referenced in the "public/index.php" file.

1. Click the New Menu () in the Contents field and select "PHP File" in the drop-down.
2. Enter the Filename "public/edit.php"
3. Enter the Text:

   <?php
   function get($key) {
       return isset($_REQUEST[$key]) ? $_REQUEST[$key] : NULL;
   }
   
   function get_file($key) {
       return (isset($_FILES[$key]) && $_FILES[$key]['tmp_name'])
           ? file_get_contents($_FILES[$key]['tmp_name'])
           : NULL;
   }
   
   function edit_president( $oid, $op ) {
       // connect to the default comand repository
       $repo = \comand::repo();
   
       // get and validate president from oid
       $p = $repo->get_object_by_oid($oid);
       if(!$p || $p->Type->Identifier != 'President') {
           return '<p>Invalid President OID.</p>';
       }
   
       // if this is an update, get and submit form values
       if($op == 'update') {
           try {
               $p->Name = get('name');
               $p->Number = get('number');
               if($photo = get_file('photo')) {
                   $p->Photo = $photo;
               }
               $p->approve();
           } catch( Exception $e ) {
               return '<p>Update Error: ' . $e->getMessage() . '</p>';
           }
       }
   
       $foid = $p->Type->get_field('Photo')->OID;
       $photo_url = "/com_webcomand/img/$oid/$foid/96x96/4";
       echo <<<FORM
   <form method="POST" enctype="multipart/form-data">
       <input type="hidden" name="op" value="update" />
       <input type="hidden" name="oid" value="$oid" />
       <label>Number</label>
       <input type="number" name="number" value="$p->Number" />
       <label>Name</label>
       <input type="text" name="name" value="$p->Name" />
       <label>Photo</label>
       <img src="$photo_url" /> 
       <input type="file" name="photo" />
       <input type="submit" value="Update" />
   </form>
   FORM;
   }
   ?>
   <html>
   <head>
       <title>Presidents Demo</title>
       <style type="text/css">
           label, input, img {display: block; margin: 4px 0;}
           input {margin-bottom 16px; padding: 4px;}
       </style>
   </head>
   <body>
   <?php edit_president( get('oid'), get('op') ); ?>
   </body>
   </html>

4. Click Approve and then Back.

Conclusion

Files in the public subfolder of a package can be accessed on the web by appending the package namespace and file path within the package's public folder to the end of the webCOMAND base URL.  If the filename is not specified at the end of the path, index.php will be discovered and served automatically, and if index.php is not found, index.html will be discovered and served if it exists.

So, you can now view and edit Presidents in the web application at:
https://<account>.webcomand.com/com_presidentsdemo_www/

• < Web Apps
• Package Routing >