Allow manual installation

[orlitzky]

Hello, I'd like to be able to install the library manually (i.e. without composer). Ultimately my goal is to package it for Gentoo, so that users can install it using our package manager, portage.

I've hit a problem though: unlike the other language install tools (rubygems, cabal, etc.), composer encourages you to use its autoload.php file instead of keeping track of includes at the top of each file. This sounds nice at first, until you try to install a library without composer -- if I use another package manager to install the library instead of composer, it doesn't work! All the include()s are missing.

Would it be possible to add the includes to the source files that need them? This should make it possible to install the library manually, and will also have the nice side effect of making the source easier to hack on without going through a composer install.

I've made the following changes locally and they were enough to get me started:

diff --git a/lib/Redmine/Api/AbstractApi.php b/lib/Redmine/Api/AbstractApi.php
index 0d64ed3..eaf61f2 100644
--- a/lib/Redmine/Api/AbstractApi.php
+++ b/lib/Redmine/Api/AbstractApi.php
@@ -2,6 +2,8 @@

 namespace Redmine\Api;

+require_once(dirname(__FILE__) . '/../Client.php');
+
 use Redmine\Client;

 /**
diff --git a/lib/Redmine/Api/Attachment.php b/lib/Redmine/Api/Attachment.php
index 5aad32b..e5068a9 100644
--- a/lib/Redmine/Api/Attachment.php
+++ b/lib/Redmine/Api/Attachment.php
@@ -2,6 +2,8 @@

 namespace Redmine\Api;

+require('AbstractApi.php');
+
 /**
  * Attachment details
  *
diff --git a/lib/Redmine/Client.php b/lib/Redmine/Client.php
index 48ae676..e025266 100644
--- a/lib/Redmine/Client.php
+++ b/lib/Redmine/Client.php
@@ -2,6 +2,27 @@

 namespace Redmine;

+require('Api/Attachment.php');
+require('Api/CustomField.php');
+require('Api/Group.php');
+require('Api/Issue.php');
+require('Api/IssueCategory.php');
+require('Api/IssuePriority.php');
+require('Api/IssueRelation.php');
+require('Api/IssueStatus.php');
+require('Api/Membership.php');
+require('Api/News.php');
+require('Api/Project.php');
+require('Api/Query.php');
+require('Api/Role.php');
+require('Api/SimpleXMLElement.php');
+require('Api/TimeEntry.php');
+require('Api/TimeEntryActivity.php');
+require('Api/Tracker.php');
+require('Api/User.php');
+require('Api/Version.php');
+require('Api/Wiki.php');
+
 use Redmine\Api\SimpleXMLElement;

 /**

[Art4]

What about creating a autoload.php file with all require_once() calls inside?

Example: lib/autoload.php (untested!)

<?php

// require this file if you aren't using composer, e.g.
// require_once(dirname(__FILE__) . '/php-redmine-api/lib/autoload.php');

require_once(dirname(__FILE__) . '/Redmine/Api/AbstractApi.php');
require_once(dirname(__FILE__) . '/Redmine/Api/Attachment.php');
require_once(dirname(__FILE__) . '/Redmine/Api/CustomField.php');
require_once(dirname(__FILE__) . '/Redmine/Api/Group.php');
require_once(dirname(__FILE__) . '/Redmine/Api/Issue.php');
require_once(dirname(__FILE__) . '/Redmine/Api/IssueCategory.php');
require_once(dirname(__FILE__) . '/Redmine/Api/IssuePriority.php');
require_once(dirname(__FILE__) . '/Redmine/Api/IssueRelation.php');
require_once(dirname(__FILE__) . '/Redmine/Api/IssueStatus.php');
require_once(dirname(__FILE__) . '/Redmine/Api/Membership.php');
require_once(dirname(__FILE__) . '/Redmine/Api/News.php');
require_once(dirname(__FILE__) . '/Redmine/Api/Project.php');
require_once(dirname(__FILE__) . '/Redmine/Api/Query.php');
require_once(dirname(__FILE__) . '/Redmine/Api/Role.php');
require_once(dirname(__FILE__) . '/Redmine/Api/SimpleXMLElement.php');
require_once(dirname(__FILE__) . '/Redmine/Api/TimeEntry.php');
require_once(dirname(__FILE__) . '/Redmine/Api/TimeEntryActivity.php');
require_once(dirname(__FILE__) . '/Redmine/Api/Tracker.php');
require_once(dirname(__FILE__) . '/Redmine/Api/User.php');
require_once(dirname(__FILE__) . '/Redmine/Api/Version.php');
require_once(dirname(__FILE__) . '/Redmine/Api/Wiki.php');
require_once(dirname(__FILE__) . '/Redmine/Client.php');

[kbsali]

@mjorlitzky i'm with @Art4 : could you give his solution a try?
Thanks

[orlitzky]

That'll work for me personally, but won't be so nice for our end users if I package it for Gentoo.

1. Users who just want to use the library will need to know about the modification we've made. If they just read the documentation, they're going to try to do require('Redmine/Client.php'); and it won't work.
2. Any application depending on the library needs to be patched (in how many places?) to run autoload.php before it tries to use the library. These packages might not be maintained by myself, so it's a lot to ask of someone else to patch potentially hundreds of PHP files.
3. I have to maintain a patch set on top of whatever the current version(s) are, and update the patch every time a new file is added to the API.

Given those downsides, I'd probably opt to just patch the source files like I've done above. I would still have to update the patch every once in a while, but at least it wouldn't bother anyone else. Of course I would rather do nothing, though =)

[osroot25]

Perhaps too simple-minded, but: Can't you just copy the lib-folder wherever you want it in your project-dir and than, in your project, register the namespace \Redmine to the corresponding dir?

[orlitzky]

First of all, copy/pasting code shouldn't be considered a solution to anything =)

The problems it causes are familiar-enough that I don't need to repeat them here, and they're the reason I'd like to be able to create a distro package for the library and install it once globally.

None of the local fixes address the real problem (please excuse the pejorative): the library appears broken for end-users who aren't me. I can't install and maintain a mangled version that requires secret voodoo for our web developers at work, and I can't ship the same to our end-users on Gentoo either. But as is, it just doesn't work.

For example, Api/Attachment.php requires the AbstractApi class. It doesn't require('AbstractApi.php');, though, so the source essentially doesn't "compile." It's missing a dependency. If you're fortunate enough to use Attachment.php in some other file that has already included AbstractApi.php, it will appear to work. But it's serendipity in that case: AbstractApi.php is still missing a dependency.

It's like if you had a Foo class inherited from Bar, and you expected everyone who uses Foo to do require('bar.php'); before they could do require('foo.php'); it's silly. Composer works around the missing dependency with the nuke-it-from-outer-space approach, but it has its own downsides. It's a bazillion times slower than just specifying the dependencies, since it has to go look around every time you use a class. And it requires an unrelated third-party build tool to be installed in order to run the library, which doesn't make any sense. You don't need GNU Make installed to run cat, do you?

[funivan]

@orlitzky if author add require it will be an overhead. It`s not good. This package optimized for php project. All use composer and this is like standard.

You can simple create bootstrap file or use composer in any system that you want. But composer you will have a lot of benefits.

You don't need GNU Make installed to run cat, do you?

Yes. you don`t But remember there are a lot of contributors to make cat work in all systems *nix. This is other story and this is hard to create php project optimized for web and for command line scripts in any platform.

[osroot25]

So, in your entire project, you don't use ANY classloader (to whom you can register the namespace Redmine, which effectively gives you the required require)?

There is NO chance you can add the three lines from http://php.net/manual/de/language.oop5.autoload.php to some script that uses this api?

[orlitzky]

@funivan Have you actually tried it? Autoload is many times slower than just adding the necessary require directives. Why? Because that's all autoload.php is doing! Except it's doing it on demand, and it doesn't know where the files are.

PHP is not a clever language. When all is said and done, the interpreter sees a big linear blob of code. If the require directive isn't there, the code won't work. So before the interpreter actually runs Attachment.php, you can be sure that it's already run AbstractApi.php. The guy who wrote the code knows where AbstractApi.php is, so the best you can do is take the unavoidable performance hit of require('AbstractApi.php') which is not even noticeable. Autoload, on the other hand, has to stop and go look for the file containing the AbstractApi class every time you use it. Try it before you tell me I'm wrong.

It's not hard to create PHP scripts that work on the web and on the command-line, and PHP is no different than C or any other language. If you do things right, they work. If you don't, they don't. Right now the library crashes out-of-the-box both on the web and the command line. With the proper require statements, it works on both, and we can package it and make it installable globally and everything is great. It's like 15 lines of requires that need to be there anyway. Not what I would call hard.

[orlitzky]

@osroot25 You're looking at this all wrong. I would like to be able to create a distribution package for php-redmine-api that works out of the box. I don't know who's going to install it, and I can't SSH into their homes and add any number of lines of code to whatever projects they're working on.

I am using this for a personal project, and I am able to work around the problem by patching the source or registering an autoloader or whatever. But I'd like to have the library installed globally and use the package manager to make sure that no one e.g. uninstalls php-redmine-api. To do that, I need to create a package for php-redmine-api. To do that, I need to kill the dependency on composer.

[funivan]

@orlitzky )) Yes i try it. If you use multiple libraries in project autoloader is best solution. If you use only 1 library and you require all classes of it - possible require is better.
But. I use redmine in several projects. They have multiple libraries with many classes. All of them use autoloader and it is much faster then require all classes of all libraries.
Read it http://blog.ircmaxell.com/2012/07/is-autoloading-good-solution.html

In general: current installation method is very good.

[orlitzky]

Loading All The Classes
The first and simplest test loads all 1000 classes. Not surprisingly, the autoload solution is
significantly slower than the hard-coded version. Shockingly over 42% slower. The hard coded test
ran in -on average- 0.0210 seconds. The autoloaded solution ran in -on average- 0.0300 seconds.
So it's clear that if you're loading all of your classes, hard-coding is clearly a better solution.

This is true not only when you "load all your classes," but whenever autoload will load the same number of classes as the manual require. In this case, I've added the exact require statements necessary, and autoload.php would load all of them. So you can expect the manual require statements to be a whole lot faster.

In your own projects, you don't need to worry either way: I've added the require statements to the library, so you can remove require('autoload.php'); from your code. You don't, then, have to require anything else yourself.

[Art4]

How about add the autoload.php file to the source and mention it in the docs as an alternative installation method? This will (probably?) solve the issue and keeps the files clean from require.

The downside is that we have to think about the autoload.php if a new file is added. Or we add a simplified autoloader in autoload.php.

[orlitzky]

@Art4 Is the goal really to keep a few require statements out of the top of a file? If so, that's probably the best you can do. But:

• It still requires everyone to require('autoload.php'); in their client code before anything will work.
• It's much slower than the manual requires
• If you ever want to go back and require only what's needed in each file , you'll have to disentangle the mess in autoload.php.
• It's harder to regenerate autoload.php than it is to add a new require at the top of a file.

It would still be better than the current situation, though, where I have no way to generate autoload.php myself.

[Art4]

It still requires everyone to require('autoload.php'); in their client code before anything will work.

Sure, but this is the same with your solution. What's the different between require('lib/Redmine/Client.php') and require('lib/autoload.php')? How can you get around this require()?

It's much slower than the manual requires

Hmm, I'm not sure. If you call Client.php in your solution it will need almost the same time. I'm not sure it will be much slower. We could banchmark this. :-)

If you ever want to go back and require only what's needed in each file , you'll have to disentangle the mess in autoload.php.

I think it will be a greater mess to keep the dependency for each file through require() calls. If e.g. sometimes Client.php depends on ClientAbstract.php you have to remember to add the new require() call.

And this is a simple untested autoloader:

<?php

// lib/autoload.php

spl_autoload_register(function ($class) {
    if (file_exists(dirname(__FILE__) . 'Redmine/Api/' . $class . '.php'))
    {
        require_once dirname(__FILE__) . 'Redmine/Api/' . $class . '.php';
    }

    if (file_exists(dirname(__FILE__) . 'Redmine/' . $class . '.php'))
    {
        require_once dirname(__FILE__) . 'Redmine/' . $class . '.php';
    }
});

It's harder to regenerate autoload.php than it is to add a new require at the top of a file.

I don't get this point, sorry. :-/

[orlitzky]

Sure, but this is the same with your solution.

I guess if the autoloader is capable of loading the Client class, it's the same. I was thinking you'd have to do both,

require('lib/autoload.php');
require('lib/Redmine/Client.php');

About the speed, I could try to convince you from first principles that the sky is not pink, but I agree a benchmark is in order. The stupidest thing that could possibly work (benchmark.php):

<?php
//require('lib/php-redmine-api/lib/autoload.php');
require('lib/php-redmine-api/lib/Redmine/Client.php');

$start_time = microtime(TRUE);
$c = new Redmine\Client("foo","bar");
$end_time = microtime(TRUE);

echo $end_time - $start_time;
?>

At the top, there are two require statements, one commented out. The first works with your autoload.php, the second with my patched library. Even if we include the start-up time for the php process, the numbers I get are waaaayyy in my favor. Averaging 10 trials, I get 0.0006499767303466801s for autoload.php and 4.37974929809571e-05s for the manual require statements. That's a 15x slowdown for autoload.php, and it would be much worse if we didn't start a PHP process each time.

I think it will be a greater mess to keep the dependency for each file through require() calls. If e.g. sometimes Client.php depends on ClientAbstract.php you have to remember to add the new require() call.

You don't have to remember anything. If you add code to e.g. Client.php that uses some class without the associated require, then it will crash. So you add the require. This is how programming without autoload.php has worked forever =)

And this is a simple untested autoloader

You need to account for the Redmine\ prefix in the class names, but yeah it seems to work. Here's what I wound up with:

<?php
// lib/autoload.php

spl_autoload_register(function ($class) {
    $class = str_replace('\\', '/', $class);

    $path = dirname(__FILE__) . '/' . $class . '.php';
    if (file_exists($path)){
      require_once($path);
    }

    $path = dirname(__FILE__) . '/' . $class . '.php';
    if (file_exists($path)) {
      require_once($path);
    }
});
?>

I don't get this point, sorry. :-/

I thought you were suggesting generating an autoload.php using composer, and then committing it to the repo. If you write your own, there's no extra work to be done.

I think keeping track of the includes is better for one's long-term sanity, but I would be grateful for this solution as well.