include/php_writeexcel/README

   1 What is it all about?
   2 ---------------------
   3 php_writeexcel is a port of John McNamara's excellent Spreadsheet::WriteExcel
   4 Perl package to PHP. It allows you to generate Microsoft Excel documents on
   5 your PHP enabled Web server without any other tools.
   6
   7
   8
   9 Where to start
  10 --------------
  11 I've included six example PHP scripts which are also taken out of the
  12 Spreadsheet::WriteExcel package and ported to PHP:
  13 - example-simple.php
  14 - example-merge2.php
  15 - example-stocks.php
  16 - example-textwrap.php
  17 - example-demo.php
  18 - example-bigfile.php
  19 All you have to do is to tar xzvf the package to a directory accessible
  20 via a web server. Then fetch any of the example scripts with your
  21 favourite web browser and Excel should come into place and show you
  22 a sheet.
  23
  24
  25
  26 Problems of porting Perl code to PHP
  27 ------------------------------------
  28 When you take a first look at both languages, they seem to be very
  29 similar: Variable names begin with a dollar sign, control structures
  30 look like in C. You don't have to change most of these things.
  31
  32 Then, there are things which can be done by find and replace: Perl subs
  33 are functions in PHP. Perl properties like $this->{prop} are $this->prop
  34 in PHP. "elsif" in Perl is "elseif" in PHP. Even porting Perl's so called
  35 OOP is not very difficult: just delete the "my $this=shift;" at the
  36 beginning of each method and then put all the methods into a class {} block.
  37 Just be aware that in Perl not the function declaration decides if the
  38 function is a method or not, but the call of the function. If you say
  39 myfunc(), it's a function, if you say $obj->myfunc(), it's a method.
  40
  41 Then the trouble begins. There were three major things I had problems
  42 with while porting SpreadSheet::WriteExcel to PHP:
  43 - function (sub) handling:
  44   In Perl's list philosophy the number of paramaters and return values
  45   are variable by design: Just use myfunc(@myarray) to pass a complete
  46   array to the function and the array's values will be the function's
  47   arguments.
  48   In PHP this is possible though undesirable as you have to use ugly
  49   things like call_user_function_array() and call_user_method_array()
  50   if you want to translate the Perl code literally.
  51 - Reference juggling:
  52   This can be very confusing when reading Perl code making
  53   excessive use of it. References are supported by PHP, but it's
  54   hard to translate them mainly due to to PHP's habit to copy
  55   EVERYTHING on any assignment. Even if you do a "$obj=new myclass();",
  56   PHP will create a copy of the instantiated class. It's sometimes
  57   hard to recognize when you have to use the "=&" operator to create
  58   a reference instead of a copy. And, hey, when the hell will the
  59   PHP developers implement a foreach loop which assigns the array
  60   values by reference?? :-(
  61 - Perl's AUTOLOAD method - PHP does not have such a thing. When
  62   a class has many properties and the AUTOLOAD method is used
  63   to simulate a set_xxx() for each property, you'll have to define all
  64   possible function calls manually.
  65
  66
  67
  68 What features are currently supported?
  69 --------------------------------------
  70 Basically all features of Spreadsheet::WriteExcel will hopefully be
  71 supported one day. However, it makes use of some Perl packages with
  72 functions I did not yet find for PHP.
  73
  74 Spreadsheet::WriteExcel uses the Parse::RecDescent package for formula
  75 support. I havn't looked for a Recursive Descent parser for PHP yet. Thus
  76 Excel formulas are not yet supported.
  77
  78 Spreadsheet::WriteExcel uses the OLE::Storage_Lite package for
  79 supporting Excel files bigger than approx. 7 MB. I have ported this
  80 package already and called it php_ole. But I really don't know how
  81 reliable it is, so use it with care!
  82
  83 All other features SHOULD work.
  84
  85
  86
  87 Documentation
  88 -------------
  89 Sorry, there is no documentation yet. You'll have to use the documentation
  90 for Spreadsheet::WriteExcel available at
  91 http://search.cpan.org/doc/JMCNAMARA/Spreadsheet-WriteExcel-0.37/WriteExcel/doc/WriteExcel.html
  92 for now. Try to translate the Perl code into PHP with the help of the
  93 examples. Please note that you have to assign variables by reference
  94 (using the =& operator) quite often!
  95
  96
  97
  98 Reporting bugs
  99 --------------
 100 If you've found a bug, please send a bug report to jonny@nurfuerspam.de.
 101 Please include "php_writeexcel" in the subject so that I can search for bug
 102 reports by searching for that string.
 103 Please note that my email address has changed. Several mails have been lost,
 104 so if you patch didn't get it, please resend it.
 105 If you get error messages, please include them in your report. Please also
 106 check your Apache error_log for messages coming from php_writeexcel.
 107 If you get corrupted Excel files, please include them in your email. If
 108 one of the demos generates a corrupted file please try to find out the
 109 differences between your file and the file you are getting from the
 110 online demo at the php_writeexcel homepage!
 111
 112
 113
 114
 115 Syntax different from SpreadSheet::WriteExcel
 116 ---------------------------------------------
 117 The worksheet methods set_h_pagebreaks() and set_v_pagebreaks() take
 118 exactly one argument which must be an array with the desired page breaks.