Ledger-CLI+GUI in Pure PHP

[pedroalbanese]

@kmpm, @larsks, @porjo, @howeyc, @qjcg, @verkaro, @jrick, @musvaage, @ghost, @whereswaldon, @aodhan-domhnaill

Greetings!

Greetings everyone; nice to meet you.

I know many of you are users of the go-ledger tool. I would like to proudly present Ledger-CLI written entirely in pure PHP. This project is a fork of go-ledger from 2021 (before Chris Howey adopted the Cobra console).

This project consists of three modules:

• Library
• CLI
• GUI

The GUI is written in PHP/HTML/AJAX and is a fully interactive alternative to go-ledger’s lweb tool. It allows you to host one or more hidden journals discreetly on a simple free subdomain with 0600 permissions. The GUI is password-protected (optional) and is the only way for users without FTP access to interact with the journal.

GUI Overview

The GUI is composed of a terminal and only two tabs:

• One for adding transactions with an unlimited number of entries
• One for importing CSV files (an idea of mine that was later incorporated into the Ledger tool in 2021)

It was designed to run simultaneously on my mobile phone and notebook, without requiring any cloud service to access the journal from multiple devices.

Source Code

• GitHub repository:
  https://github.com/pedroalbanese/ledger/tree/master/php

Live Demos

If you want to test it on a server, simply add the files ledger.php, ledger-cli.php, limport.php, and one of the index.php files.
I created three different themes, available here (my homepage):

• Default:
  http://albanese.atwebpages.com/ledger/index.php
• Light:
  http://albanese.atwebpages.com/ledger/light.php
• Dark:
  http://albanese.atwebpages.com/ledger/dark.php

The passphrase is "admin123".

Preview:

Compatibility

This project consists of ledger-cli implemented in pure PHP, 100% compatible with Chris Howey’s Ledger tool. It enables browser integration without sacrificing terminal capabilities or underlying functionality, removing the need to keep a machine permanently running an lweb server. Use --help to explore the tool. Try bal --payee="Coffee".

Suggestions and feedbacks are very welcome.

Att.

[howeyc]

Quite interesting. I enjoyed playing with it.

I did notice it let me add an unbalanced transaction. Not sure if that's intentional.

[pedroalbanese]

Indeed! I hadn't considered this possibility. It's not intentional, but I'll need to insert, for example, zero-amount transactions into the rules.ledger file included in mastercard.ledger for Bayesian classification, so it's not all bad. I wrote this in just over 20 hours; I need to test it carefully and apply proper error handling. It's still in the prototypical phase. It needs some improvements, but I've already achieved 95% of what I intended.

I will likely restrict unbalanced transactions but will allow zero-amount transactions.

I wrote this code to interact with your implementation, not to supplant or replace it. Ledger in Go was the project that taught me to program in Go, and I've been using Ledger ever since; this is a revisit. That's the clone of the clone.

Thanks for the feedback and the Ledger!

[musvaage]

@pedroalbanese

PR opened on rendering issue.

The index-dark.php file has correctly rendered strings.

[pedroalbanese]

@musvaage

I'm sorry! I hadn't realized there were still comments in Portuguese. The best alternative is to translate everything to English. Thank you! Let me know if it worked.

[musvaage]

Are you referring to adding more period options in the PHP tool?

$ sed -i "s/suppored/supported/g" ledger/date.go
$

more comments to translate

$ sed -n '78p; 403p; 468p' ledger/php/ledger.php
    // ADICIONADO: Método equals() necessário para o handleBalance()
    // ADICIONADO: Método transactionsByPeriod() necessário para o handleRegister()
    // ADICIONADO: Método balancesByPeriod() necessário para o handleBalance()
$ 

printed lines with non-ascii strings

$ perl -nle 'print "$. $_" if m/[^[:ascii:]]/' ledger/php/limport.php
369             // CORREÇÃO: Se --neg estiver ativo, inverte o sinal do amount original
397         // Remove espaços extras
400         // Se temos um formato específico configurado
455             // Formatos com dia/mês com 1 dígito
456             'j/n/Y',      // 31/12/2023 (sem zero à esquerda)
460             // Datas apenas numéricas (auto-detectar)
469                 // Verificar se a data é válida (não é falsa como 31/02/2023)
471                 // getLastErrors() pode retornar false se não houver erros
478         // Se não funcionou com os formatos acima, tentar detecção inteligente
$ 

also from the foregoing file

$ sed -n '404p; 410p; 428p; 430p; 435p; 440p; 445p; 449p; 453p; 458p' ledger/php/limport.php
            // Tentar o formato configurado
            // Tentar variantes com diferentes separadores
        // Lista mais abrangente de formatos (em ordem de prioridade para Brasil)
            // Formatos brasileiros primeiro
            // Formatos ISO/internacionais
            // Formatos americanos
            // Com barras invertidas
            // Com hora (ignora a hora)
            'Y-m-d\TH:i:s',   // 2023-12-31T14:30:00 (ISO com T)
            'n/j/Y',      // 12/31/2023 (EUA sem zero)
$ 

[pedroalbanese]

Check now, please.

[musvaage]

$ file ledger/php/*.php
ledger/php/equity.php:      a /usr/bin/env php script, ASCII text executable
ledger/php/index-dark.php:  PHP script, ASCII text
ledger/php/index-light.php: PHP script, ASCII text
ledger/php/ledger-cli.php:  a /usr/bin/env php script, ASCII text executable
ledger/php/ledger.php:      PHP script, Unicode text, UTF-8 text
ledger/php/limport.php:     a /usr/bin/env php script, ASCII text executable
$ 

The ledger.php file contains currency symbols; it's encoding won't be affected after translating the comment line to English.

$ sed -n '78,82p' ledger/php/ledger.php
    // ADICIONADO: Método equals() necessário para o handleBalance()
    public function equals(SimpleRational $other): bool
    {
        return abs($this->value - $other->value) < 0.000001;
    }
$ 

---

This typo was fixed over in the repository of @howeyc.

https://github.com/howeyc/ledger/issues/44

$ sed -n '25p' ledger/date.go
// Periods suppored by ledger
$ 

FWIW, the same named file of @howeyc, has this content which your file does not.

PeriodDay Period = "Daily"

[pedroalbanese]

Test it again, please.

[musvaage]

As expected with an absence of Portuguese text with non-ascii characters the ledger file remains UTF-8 encoded.

$ date
fre 20 mar 20:54:25 CET 2026
$ git clone -q https://github.com/pedroalbanese/ledger.git
$ file ledger/php/ledger.php
ledger/php/ledger.php: PHP script, Unicode text, UTF-8 text
$ perl -nle 'print "$. $_" if m/[^[:ascii:]]/' ledger/php/ledger.php
26             $value = preg_replace('/[\$\€\£\¥]/', '', $value);
287         $testStr = preg_replace('/[\$\€\£\¥\s,]/', '', $testStr);
$  

I can confirm after dumping the comment lines from the *.php files that these no longer contain any Portuguese text.

---

Would you be amenable to enabling a Wiki for the repository?

Then in Wiki pages could be included instructions on download, building, and running the program.

The reason for the suggestion would be to not clutter up the top level README.md file with seldom referenced information.

---

Could you clarify in a comment to this ticket the basis of the seeming disparity in the contents of the date.go files?

$ lynx -dump https://raw.githubusercontent.com/howeyc/ledger/refs/heads/master/date.go \
> | sed -n '28,38p'
// Periods supported by ledger
const (
        PeriodDay      Period = "Daily"
        PeriodWeek     Period = "Weekly"
        Period2Week    Period = "BiWeekly"
        PeriodMonth    Period = "Monthly"
        Period2Month   Period = "BiMonthly"
        PeriodQuarter  Period = "Quarterly"
        PeriodSemiYear Period = "SemiYearly"
        PeriodYear     Period = "Yearly"
)
$ 

[pedroalbanese]

As expected with an absence of Portuguese text with non-ascii characters the ledger file remains UTF-8 encoded.

It was not my intention to modify the implementation of Ledger 0.3.2 in Go, it's intact since the fork, I will analyze it calmly on Monday. I removed the non-ASCII characters.

Could you clarify in a comment to this ticket the basis of the seeming disparity in the contents of the date.go files?

The Daily period was added to Chris Howey's code between 2021 and now, but it wasn't present at the time. My implementation is based on the original version from that period, which didn't include it. I've since added it to my PHP and Crystal ports to align with the current codebase.

[musvaage]

At the time, though I wasn't sure, I'd solely expected Portuguese language in the code's comments.

But just to run an alternate check, I tested for changes in the files' encoding after the Portuguese comments were translated.

I factually only brought up the *.php files encoding as some have changed to ASCII text when the Portuguese was translated.

[pedroalbanese]

Yes, it was a great contribution! I thank You. And feel free make suggestions and tips.

I factually only brought up the *.php files encoding as some have changed to ASCII text when the Portuguese was translated.

It's good for maintaining uniformity. But it's Github that's changing the file format; I don't have access to the original files here. I'm editing the files directly on the server.

[pedroalbanese]

I was editing directly on the server, so I don't have control over how GitHub handles the file encoding when displaying or editing online. The ASCII conversion was intentional to keep things consistent and avoid any encoding issues.

Look the original files and translated versions:

dark.php:       PHP script, Unicode text, UTF-8 text
dark_en.php:    PHP script, ASCII text
equity.php:     C++ source, ASCII text
index.php:      PHP script, Unicode text, UTF-8 text
ledger-cli.php: C++ source, ASCII text
ledger.php:     PHP script, ASCII text
light.php:      PHP script, Unicode text, UTF-8 text
light_en.php:   PHP script, ASCII text
limport.php:    C++ source, ASCII text

It seems ASCII encoding is automatic for files that don't contain Unicode.

I added Daily Period support to the Go code.

[pedroalbanese]

Apropos, despite the encoding and translation issues, does the code work? Is it useful?

[musvaage]

useful

My time allocated was to improve the documentation which might ease other developers review of the software.

Considering the scope of the changes, a sole remaining suggestion, 2 identical comments in ledger.php could be reworded.

-             // Remove currency characters
+             // Remove dollar, euro, pound sterling, yen and yuan signs