-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hello,

I would like to propose a new component to ease the execution of
external processes.

I created an object oriented execution wrapper some time ago for another
project I am currently working on. After all the positive feedback I got
from different people using this utility I realized this could possibly
an interesting contribution to the eZComponents. I wrote a requirements
document for such a component which you can find attached to this mail.
As you will see from the requirements document. The current
implementation could easily be used as a basis for the creation of a
more sophisticated process handler, which I would like to write.

Regards,
Jakob
- --
Jakob Westhoff                                         (GPG 0xCBF7FC6A)
http://westhoffswelt.de
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iQEcBAEBAgAGBQJJgKaMAAoJEE0XwzzL9/xq8CgH/3/hWsp1pOvXaseupol6CrKk
ChEUqK3oWMvZbU5V9HLyHW8pk81V4Jb5LQTST6bc3kowC+4jGQG7OMPxyc2gACLT
zxa51N3oekMxPZpqosgjvHSbOAn+xKI5Qr69oTPXOx8v6VPrS6V2hhM+c3E1dGDt
mr4Ih9jPWU4iVK3jRtjRx7AaBN/cOiL5+dniiIQQCvqGGMHH0xIl4o9YPXBWr3Dc
ZWqSYv56EcPRK/EucUWpjaqa2NSNhEXvIJypIJKilmoS2iqO4ukwGL9Xi30RLpc/
2MTk9l8EQ/ltcleh0jGoG6rwjt+94obYnb/FyLkpVvZ1Vl27BmiKj0FpHs1l3Go=
=b+v7
-----END PGP SIGNATURE-----
eZ Components: SystemProcess, Requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:Author: Jakob Westhoff
:Revision: $Revision: 14 $
:Date: $Date: 2009-01-28 19:30:31 +0100 (Mi, 28. Jan 2009) $

Introduction
============

Description
-----------

The SystemProcess component presents a set of features to execute and handle
external applications in an easy and manageable way. It takes care of the
underlying system calls and specialties like different path formatting or
signal handling to provide a platform independent but yet flexible way to work
with external applications.

Furthermore it automagically escapes the given command or argument parts to
make code injection less easy and ensure correct command execution.


Current implementation
----------------------

The currently available implementation provides easy means to handle
synchronous as well as asynchronous program executions using the proc_*
function set from php. It is fully unit tested. At the current development
stage it is does not ensure any cross platform compatibility with windows or
any other system them plain Linux. Nevertheless it should also work on other
\*nix based systems.  Because of not taking windows support into account,
currently no way of cross platform path creation is implemented either.

It is available at::
    
    svn://svn.pureenergy.cc/systemProcess


Requirements
============

The SystemProcess component needs to fulfill the following requirements from
the current point of view:

Execution
---------

- Provide an easy but yet effective way of executing external processes,
  retrieving their output after they finished. (Synchronous execution)

- Provide means to read from the file descriptors (STDOUT, STDERR, custom
  descriptors) an executed process provides during while it is currently
  running. (Asynchronous execution)

- Provide a string representation of the built shell command without
  necessarily executing it.

- Receive the probably non zero exit codes after process execution finished.

- Send arbitrary POSIX signals to an asynchronously running process. (This can
  obviously not be done on windows systems.)

- Terminate a currently running process. This is only feasible for
  asynchronously running processes where such operations can be triggered while
  the process is running.

Argument preparation
--------------------

- Handle the correct shell escaping needed for commands and arguments to
  prohibit the injection of shell commands.

- Provide platform independent means to specify file paths. (eg. on Linux
  systems "/" is used a directory separator whereas on windows "\\" is used.)

File descriptors
----------------

- Provide access to the STDIN file descriptor to send arbitrary data to the
  executed application. This may only be reasonable during an asynchronous
  execution.

- Allow the redirection of certain file descriptors to files as well as other
  file descriptors. (eg. Send all STDOUT output to "/tmp/foobar", or send
  STDERR output to STDOUT)

- Define custom file descriptors which can be accessed to send or receive
  necessary data during the execution. 

- Allow piping the output of one SystemProcess to another one by building the
  appropriate command line (eg. "echo foobar|cat", where a SystemProcess object
  for echo as well as for cat exists.)

Environment
-----------

- Set a working directory the execution should be handled in

- Provide a custom set of environment variables used during the application
  execution.


Design goals
============

The workflow of a creating a SystemProcess object applying certain arguments as
well as options to it and finally spawning the process should be intuitive as
possible. The best way to achieve such an intuitive API would be to design it
having the fluent interface pattern in mind. The used interface should look
something like this::

    new ezcSystemProcess( 'echo' )->argument( 'foo' )->execute();

This kind of interface is occurs to be the cleanest object-oriented way of
assembling a command line to me. Therefore the user should be able to easily
get used to the structure processes are defined and finally spawned.

It should be taken into account that the usual way of informing the parent
process of errors during the execution of any child is by using error codes
which are simply returned after the child terminated. These error codes need to
be made available to the caller. The execute function, if not called
asynchronously could just return the appropriate error code. From a strict
object oriented view it an exception should be thrown if a non zero exit code
is detected. Nevertheless some applications use non zero exit codes even if
the execution did not cause a fatal error. Therefore it might be a good idea to
create an option if an exception should be thrown or the error code should just
be returned. This option should be local for any created SystemProcess object
to not interfere with large scale applications where a global change of this
kind of option could introduce certain side effects.

Currently a well documented implementation of this exists (See `Current
implementation`_ for details). Not all features are completely covered in a
satisfactory way yet. But this implementation could be seen as a possible base
for the work to be done.

Some usage examples of the current implementation can be found on its project
page, which can be reached under::
    
    http://westhoffswelt.de/projects/systemprocess.html
   


..
   Local Variables:
   mode: rst
   fill-column: 79
   End:
   vim: et syn=rst tw=79

Attachment: requirements.txt.sig
Description: Binary data

-- 
Components mailing list
Components@lists.ez.no
http://lists.ez.no/mailman/listinfo/components

Reply via email to