speedylom/whendoyoufinish

Use PHP and Toggl to allow others to track your workday.

WhenDoYouFinish

A single page app that uses Toggl to display an estimated finishing time based on fixed working hours written in PHP.

If you are working remotely and frequently get the following questions throughout your working day:

When do you finish? How much longer do you have left? What time do you finish?

Then WhenDoYouFinish will allow you to divert that question leaving you to carry on with your work uninterrupted. Simply direct your spouse/child/friend/goldfish at your WhenDoYouFinish page and let them find out for themselves.

How it works?

WhenDoYouFinish uses the entries (recorded and running) from your Toggl account to provide a total amount of time worked, this time worked is compared against a fixed working day length to provide an estimated finish.

What do you need?

In order to be able to run your own WhenDoYouFinish page you'll need a:

• Free Toggl account (or paid)
• Machine running PHP 8.0 (or later)
• Fixed workday length (i.e. 7.5 hours)
• Knowledge of running commands from a terminal

Getting started

To get started on running your own WhenDoYouFinish page check you can meet the requirements below and then follow the installation steps.

Requirements

The technical requirements for this project are:

• PHP 8.0+
• composer
• curl
• JSON

Installation

Providing your machine has been set up to meet the technical requirements, the first step is to clone this repository to your machine that will run your page.

git clone https://github.com/SpeedyLom/WhenDoYouFinish.git

Once the project has been cloned then use composer to install any dependencies:

cd WhenDoYouFinish
composer install --no-dev

Configuration

After installing any dependencies copy the configuration.example.json to configuration.json and set your:

• Toggl API token
• Environment (production)
• User agent (your email address)
• Workday length in minutes (default 7.5 hours)
• Toggl workspace ID (numbers proceeding /settings/general after following this URL)

{
  "api_token": "123456789ABCDEFG123456789ABCDEFG",
  "environment": "production",
  "user_agent": "[email protected]",
  "workday_length_in_minutes": 450,
  "workspace_id": 1234567
}

Running

With the configuration in place you can start the application making the page available to friends and loved ones.

PHP Built-in Server

One of the simplest ways to start your WhenDoYouFinish instance is to use PHP's Built-in web server which can be done from the root of your WhenDoYouFinish/ directory.

php -S 0.0.0.0:8080

Usage

With your instance up and running you can then access the page on port 8080 at your machine's local IP address i.e. http://192.168.0.42:8080.

If you are unsure of your machine's IP address you can use a command like hostname to find it out:

hostname -I

whendoyoufinish's Issues

📘 Add unit tests to the code base

User story

As a developer, I want unit tests added to the code base so that I can be more confident that my changes haven't broken existing functionality.

Additional context

We should add tests to existing code so that functionality is preserved when new features are added.

Acceptance criteria

1. Given I am working on the code base when I complete changes then I should have to run tests on the code.

📘 Add a changelog

User story

As a repository viewer, I want a changelog so that it is easier to see the projects history.

Additional context

Add a CHANGELOG.md to the project based on keep a changelog.

Acceptance criteria

1. Given I am a repository viewer when I view the repository then there will be a CHANGELOG.md file in the root.

📘 Update the application with the principles of SOLID

User story

As a developer, I want to use the principles of SOLID so that they are easier to maintain going forwards.

Additional context

The Toggl class specifically is doing too much and should be split out.

Acceptance criteria

1. Given I am a developer when I use the classes then they will be for a specific purpose.

📘 Replace direct uses of cURL with a class

User story

As a developer, I want the direct uses of cURL replaced with a class so that tests can be run without making requests.

Additional context

Tests on the Toggl class make live requests we should replace the direct uses of cURL with a class so that it can be mocked as detailed in this Stack Overflow answer.

Acceptance criteria

1. Given I am making a cURL request when I create a cURL handle then it will be as an instance of a cURL class.

📘 Replace the custom template engine

User story

As a developer, I want the custom HTML template engine replaced with an external package so that there is less to maintain.

Additional context

We should be able to replace HtmlTemplate with Mustache as the templates are logic free.

Acceptance criteria

1. Given I am a developer when I want to use a template then mustache will be used.
2. Given I am a developer when I view the src/ then there won't be HtmlTemplate or another custom template engine.

📘 Provide further information in the README

User story

As a user, I want more information provided in the README.md so that I don't have to research it on my own.

Additional context

We could do with adding the following information:

• A link to Toggl
• A more detailed installation
• Steps on how to get the Toggl API and workspace IDs
• Fixing issues with cURL and SSL on Windows
• Add the workflow badge

Acceptance criteria

1. Given I am viewing the README.md when I read the summary section then there will be details of Toggl and a link.
2. Given I am viewing the README.md when I read the installation section then it will have at least a bulleted list.
3. Given I am viewing the README.md when I read the environment section then it will explain how to get the required Toggl IDs.

📘 Replace the use of $_ENV in the classes

User story

As a developer, I want to replace the use of $_ENV in the classes so that it can be mocked in testing.

Additional context

The use of the $_ENV superglobal is causing issues when creating tests for the classes. If we refactor to replace the use of the superglobals then we should be able to mock the class effectively.

Acceptance criteria

1. Given I have an instance of the Toggl class when I call makeCurlRequest() then it won't use the superglobals.
2. Given I have an instance of the Converter class when I call determineRemainingWorkdayInMinutes() then it won't use the superglobals.

🐛 Recorded Toggl entries not being included in total time worked

Describe the bug

The recorded entries for the day are not being included in the day's total time worked.

To Reproduce

Steps to reproduce the behaviour:

1. Record an entry in Toggl
2. Start a new entry in Toggl
3. Refresh the WhenDoYouFinish page
4. See that total time for the day only includes the amount from the new running entry

Expected behaviour

Once a Toggl entry has been recorded it will be included towards the total of time worked when viewing the WhenDoYouFinish page on the same day.

📘 Use PHP 8.1 readonly properties

User story

As a developer, I want the project updated to PHP 8.1 so that I can use the new features of the language.

Additional context

There are new features in PHP 8.1 that can be used to tidy up the code:

• Readonly properties

Acceptance criteria

1. Given I am a developer when I checkout the project then the minimum listed PHP version will be 8.1.
2. Given I am a developer when working on the source code then readonly properties will be used where applicable.

📘 Rewrite using TDD

User story

As a developer, I want the project rewritten using Test-Driven Development so that unit tests are written to cover the behaviour of the system.

Additional context

Use the development process of TDD.

Acceptance criteria

1. Given I am a developer when I have changes to make to the code base then I will use TDD to write to write tests before code.

📘 Improve the UI

User story

As a user, I want the user interface updated so that it isn't so bland.

Additional context

It would be good to have some colour and icons.

Acceptance criteria

1. Given I am a user when I view the page then it won't be monochrome.

📘 Add current time entry to estimation

User story

As a user, I want the countdown to include any running entries so that it doesn't provide an estimate with missing time.

Additional context

Time of currently running entries isn't returned by the reports API so the amount of time worked can be off by a large amount.

Acceptance criteria

1. Given I have a running time entry when my finish time is calculated then the running entry will be included in the calculation.

📘 Use a templating engine to define content

User story

As a developer, I want the HTML to be contained in templates so that content is defined separately.

Additional context

Either implement or use and existing templating engine.

Acceptance criteria

1. Given I am a developer when I am defining HTML content then it will be in a template.