Much hello,
We are working on a new version of ManiaLib (PHP framework for manialinks). In order to make things simplier, it will be split in several standalone packages (like Symfony components).
The first package we're working on is the evolution of ManiaLib\Gui and is made for building the actual XML of manialink pages.
We are keeping some stuff from ManiaLib\Gui, but are still starting from scratch and breaking most of the compatibility, so don't expect to easilly convert old Manialib code to this new lib.
The good news is that it uses a new namespace (ManiaLib\Manialink) so you can actually use both at the same time without conflict if you'd like.
As stated above, ManiaLib\Manialink is standalone. It is made for abstracting XML. Therefore you can use it wherever you fancy, from Web apps (typically manialinks) to controllers (eg. ManiaLive).
Installation is easy with composer, and usage, after a bit of learning, should feel confortable and logical.
It's a work in progress. Although functionnal, it lacks some classes and methods. We will break things without notice. Still, we think working on it openly on github is a nice way to do. We can also consider suggestions for features.
https://github.com/maniaplanet/manialib-manialink
I'll be glad to answer questions you might have!
ManiaLib\Manialink: our (new) PHP lib for building XML
Moderator: NADEO
ManiaLib\Manialink: our (new) PHP lib for building XML
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer!
Re: ManiaLib\Manialink: PHP lib for building XML
I have a question :
- Why making a new version from scratch whereas the current version seems to work correctly?
- Why making a new version from scratch whereas the current version seems to work correctly?
Elle est où la poulette ?
Re: ManiaLib\Manialink: PHP lib for building XML
I started ManiaLib when i was an intern back in 2008. While it works very well, we've been working with it daily for the past 5 years, so we have a very clear vision of what's working and what's cumbersome or not working. Starting from scratch allows to break whatever we want, build a very clean and logical architecture. It also helps moving faster.
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer!
Re: ManiaLib\Manialink: our (new) PHP lib for building XML
Starting from scratch sometimes is the best way to improve a project. I know this from my own projects ^^
I looked through the code, and I have some suggestions on how you can improve the quality of it and to make it easier to understand and thus to use.
1. Add PHP Docblocks
It is important, that you start adding all the PHP-Docblocks. Because if you do not add them right at the beginning, you will never add them at all. It will not only help others understanding your code, it will also help yourself when you return to old code after some months, as you may have forgotten what it does.
Most important is that return types and incoming parameter types are named in the docblocks. PHP has a weak type safety, this makes the documentation of the types even more important. For example in the Elements classes, the return types are already defined (helping the IDE providing the autocomplete), yet not a single incoming parameter type has been specified. What does Label->setAutonewline() expect? A boolean (as it is a flag of the label), or a string (as it will be an XML attribute in the end)?
I also saw the following docblock:
While a valid docblock in other languages, a PHP Docblock requires the parameter name to be written into the @param line. So this block should look like:
Take the time for adding and correcting the docblocks -- It will help in the future
2. No Public Properties
I think it is no secret that public properties should be avoided. Yet Cards\Box and Cards\LabelBox have public ->bg and ->label. As soon as I set one of these properties to something other than Node instances, I think ManiaLib will break somewhere. Provide Setters and Getters as you did in the other classes to refuse setting wrong values to the properties.
So when you are already breaking old code, then use this situation to remove the public properties ^^
3. Bad Example
The last one is more a personal preference.
On github, you have the following example code:
While using fluent interface is nice, you switch the context several times in this code block. With ->bg you go to the background element to set the style, and then return with getParent() to the original one, and do that again with ->label.
In my opinion, the following, while a little longer, makes clearer what happens:
Maybe with this you notice that $ui gets appended twice to $frame?
I looked through the code, and I have some suggestions on how you can improve the quality of it and to make it easier to understand and thus to use.
1. Add PHP Docblocks
It is important, that you start adding all the PHP-Docblocks. Because if you do not add them right at the beginning, you will never add them at all. It will not only help others understanding your code, it will also help yourself when you return to old code after some months, as you may have forgotten what it does.
Most important is that return types and incoming parameter types are named in the docblocks. PHP has a weak type safety, this makes the documentation of the types even more important. For example in the Elements classes, the return types are already defined (helping the IDE providing the autocomplete), yet not a single incoming parameter type has been specified. What does Label->setAutonewline() expect? A boolean (as it is a flag of the label), or a string (as it will be an XML attribute in the end)?
I also saw the following docblock:
Code: Select all
/**
* Returns the X position of an element in relation to another element and
* according to their respective alignments
*
* @param int X position of the parent element
* @param int Width of the parent element
* @param string Horizontal alignement of the parent element
* @param string Horizontal alignement of the element you want to place
* @return int Calculated X position of the element you want to place
*/
final public static function getAlignedPosX($posX, $sizeX, $halign, $newAlign)
Code: Select all
/**
* Returns the X position of an element in relation to another element and
* according to their respective alignments
*
* @param int $posX X position of the parent element
* @param int $sizeX Width of the parent element
* @param string $halign Horizontal alignement of the parent element
* @param string $newAlign Horizontal alignement of the element you want to place
* @return int Calculated X position of the element you want to place
*/
final public static function getAlignedPosX($posX, $sizeX, $halign, $newAlign)
2. No Public Properties
I think it is no secret that public properties should be avoided. Yet Cards\Box and Cards\LabelBox have public ->bg and ->label. As soon as I set one of these properties to something other than Node instances, I think ManiaLib will break somewhere. Provide Setters and Getters as you did in the other classes to refuse setting wrong values to the properties.
So when you are already breaking old code, then use this situation to remove the public properties ^^
3. Bad Example
The last one is more a personal preference.
On github, you have the following example code:
Code: Select all
$ui = LabelBox::create()
->setPosn(0, -35)
->setSizen(100, 10)
->appendTo($frame)
->bg
->setStyle(Bgs1::BgTitle3)
->getParent()
->label
->setText('Much foobar')
->setTextSize(4)
->getParent()
->appendTo($frame);
In my opinion, the following, while a little longer, makes clearer what happens:
Code: Select all
$ui = LabelBox::create()
->setPosn(0, -35)
->setSizen(100, 10)
->appendTo($frame);
$ui->bg->setStyle(Bgs1::BgTitle3);
$ui->label->setText('Much foobar')
->setTextSize(4)
$ui->appendTo($frame);
Re: ManiaLib\Manialink: our (new) PHP lib for building XML
Thanks for you feedback!
Yep, it's planned. Right now i'm focusing on the code itelf to move faster since MP3 is our priority. But obviously i'd like to document the code to generate a nice doc.m4rcel wrote:1. Add PHP Docblocks
I agree that theoretically it's bad. But it's a tradeoff for simplicity's sake. I might add getters on those open source objects to have a cleaner project, even if we keep on using public props in our own cards internally.m4rcel wrote:2. No Public Properties
I agree. It was a quick and dirty example to see if it worked, but i would probably write it like you did.m4rcel wrote:3. Bad Example
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer!
Re: ManiaLib\Manialink: our (new) PHP lib for building XML
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer!
Re: ManiaLib\Manialink: our (new) PHP lib for building XML
Why don't make documentation while you're coding?gouxim wrote:Yep, it's planned. Right now i'm focusing on the code itelf to move faster since MP3 is our priority. But obviously i'd like to document the code to generate a nice doc.m4rcel wrote:1. Add PHP Docblocks
It makes coding easier and making the documentation quicker ...
Global moderator | Dutch moderator | Laddermoderator | ManiaWiki moderator
Server Manager/webmaster of Smurfen.net, join us on Canyon, Valley and Royal!
ESL (Game) Staff Head for TrackMania (Stadium, Canyon and Valley).
Server Manager/webmaster of Smurfen.net, join us on Canyon, Valley and Royal!
ESL (Game) Staff Head for TrackMania (Stadium, Canyon and Valley).
Re: ManiaLib\Manialink: our (new) PHP lib for building XML
TheM wrote:Why don't make documentation while you're coding?
gouxim wrote:focusing on the code itelf to move faster since MP3 is our priority
Nop it does not ^^TheM wrote:It makes coding easier
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer!
Re: ManiaLib\Manialink: our (new) PHP lib for building XML
Then I suppose you're not doing it right ...gouxim wrote:Nop it does not ^^
Global moderator | Dutch moderator | Laddermoderator | ManiaWiki moderator
Server Manager/webmaster of Smurfen.net, join us on Canyon, Valley and Royal!
ESL (Game) Staff Head for TrackMania (Stadium, Canyon and Valley).
Server Manager/webmaster of Smurfen.net, join us on Canyon, Valley and Royal!
ESL (Game) Staff Head for TrackMania (Stadium, Canyon and Valley).
Re: ManiaLib\Manialink: our (new) PHP lib for building XML
Short answer: it is a bit presumptuous from you to say this
Longer answer: I work with manialib on a daily basis, i have written it, and i work with netbeans which provides code hints and completion. So in the end, documenting it will not make coding easier for me. It will just be more things to write and maintain.
Longer answer: I work with manialib on a daily basis, i have written it, and i work with netbeans which provides code hints and completion. So in the end, documenting it will not make coding easier for me. It will just be more things to write and maintain.
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer!
Who is online
Users browsing this forum: No registered users and 1 guest