<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Naveed Malik</title>
    <description>The latest articles on DEV Community by Naveed Malik (@malkoo1).</description>
    <link>https://dev.to/malkoo1</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4200141%2F8697d26d-4838-4478-85b7-0aa9a1ccc146.jpg</url>
      <title>DEV Community: Naveed Malik</title>
      <link>https://dev.to/malkoo1</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/malkoo1"/>
    <language>en</language>
    <item>
      <title>Multi-campus inside a multi-tenant Laravel app: our reads were airtight, our writes were not</title>
      <dc:creator>Naveed Malik</dc:creator>
      <pubDate>Sun, 01 Nov 2026 12:06:55 +0000</pubDate>
      <link>https://dev.to/malkoo1/multi-campus-inside-a-multi-tenant-laravel-app-our-reads-were-airtight-our-writes-were-not-501j</link>
      <guid>https://dev.to/malkoo1/multi-campus-inside-a-multi-tenant-laravel-app-our-reads-were-airtight-our-writes-were-not-501j</guid>
      <description>&lt;p&gt;We build &lt;a href="https://karobar.cloud" rel="noopener noreferrer"&gt;Karobar&lt;/a&gt;, a school management system for schools in Pakistan. It is a Laravel API with a database per school (tenant), and a React front end.&lt;/p&gt;

&lt;p&gt;Then schools started asking for a second campus. This post covers how we added campuses &lt;em&gt;inside&lt;/em&gt; a tenant, and five rules we learned the hard way. The biggest lesson: we tested who could &lt;strong&gt;read&lt;/strong&gt; a campus's rows, and never tested where a &lt;strong&gt;write&lt;/strong&gt; could land.&lt;/p&gt;

&lt;h2&gt;
  
  
  Tenant vs campus: why a campus is not a tenant
&lt;/h2&gt;

&lt;p&gt;The obvious move is "one campus = one tenant". We didn't do that. A school with three campuses is still one school: one curriculum, one fee structure, one owner who wants a single number for "fees collected this month". Separate databases would turn every school-wide question into a cross-database job.&lt;/p&gt;

&lt;p&gt;So a campus is a row in a &lt;code&gt;branches&lt;/code&gt; table inside the school's own database. Around fifteen "root" tables carry a &lt;code&gt;branch_id&lt;/code&gt;: students, staff, classes, vehicles, books, expenses, and so on. Everything else reaches a campus through a parent. An attendance record belongs to a student, a section belongs to a class.&lt;/p&gt;

&lt;p&gt;The active campus travels on each request as an &lt;code&gt;X-Branch-Id&lt;/code&gt; &lt;strong&gt;header&lt;/strong&gt;, not as a JWT claim. A separate core service mints our tokens, and it knows nothing about a school's interior. Which campuses a user may see lives in a &lt;code&gt;branch_user&lt;/code&gt; table, because one person (a regional head, or an accountant keeping two sets of books) can cover more than one.&lt;/p&gt;

&lt;h2&gt;
  
  
  Reads: one scope, applied through relations
&lt;/h2&gt;

&lt;p&gt;A request-aware &lt;code&gt;BranchScope&lt;/code&gt; service narrows queries. For root tables it is a simple &lt;code&gt;whereIn('branch_id', …)&lt;/code&gt;. For child tables it goes through the relation:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight php"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;function&lt;/span&gt; &lt;span class="n"&gt;applyThrough&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;Builder&lt;/span&gt; &lt;span class="nv"&gt;$query&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="nv"&gt;$relation&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="nv"&gt;$column&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'branch_id'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;bool&lt;/span&gt; &lt;span class="nv"&gt;$keepNull&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="kt"&gt;Builder&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt; &lt;span class="nv"&gt;$this&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;isNarrowing&lt;/span&gt;&lt;span class="p"&gt;())&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nv"&gt;$query&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="nv"&gt;$onCampus&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;fn&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;Builder&lt;/span&gt; &lt;span class="nv"&gt;$inner&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nv"&gt;$this&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;applyTo&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$inner&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$column&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

    &lt;span class="c1"&gt;// A row that points at nothing belongs to the school, not to nobody.&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$keepNull&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nv"&gt;$query&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;where&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;fn&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;Builder&lt;/span&gt; &lt;span class="nv"&gt;$outer&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nv"&gt;$outer&lt;/span&gt;
            &lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;whereDoesntHave&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$relation&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;orWhereHas&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$relation&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$onCampus&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nv"&gt;$query&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;whereHas&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$relation&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$onCampus&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In a QA pass we tried a &lt;code&gt;?branch_id=&lt;/code&gt; query parameter, a forged &lt;code&gt;X-Branch-Id&lt;/code&gt;, and fetching another campus's record by id. All three were blocked, the last with a &lt;code&gt;404&lt;/code&gt; rather than a &lt;code&gt;403&lt;/code&gt;, so the id doesn't leak. Reads were airtight.&lt;/p&gt;

&lt;h2&gt;
  
  
  Writes: the half we forgot
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;branch_id&lt;/code&gt; was fillable. A trait stamped the campus on new rows &lt;strong&gt;only when the payload didn't name one&lt;/strong&gt;. So a campus admin who sent &lt;code&gt;branch_id&lt;/code&gt; in a create body could file a student, or a class, at any campus they liked.&lt;/p&gt;

&lt;p&gt;Every campus test we had asked &lt;em&gt;what can this person see&lt;/em&gt;. None asked &lt;em&gt;where can this person's write land&lt;/em&gt;. The fix sits in the shared CRUD controller and runs &lt;strong&gt;before&lt;/strong&gt; the write. A check after saving would only reject a row that already sits at the wrong campus.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight php"&gt;&lt;code&gt;&lt;span class="k"&gt;protected&lt;/span&gt; &lt;span class="k"&gt;function&lt;/span&gt; &lt;span class="n"&gt;guardBranchPlacement&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;array&lt;/span&gt; &lt;span class="nv"&gt;$data&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="kt"&gt;void&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nv"&gt;$asked&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nv"&gt;$data&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'branch_id'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;blank&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$asked&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// the stamping trait picks the campus&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="nv"&gt;$allowed&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;app&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;BranchScope&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="n"&gt;class&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;allowedBranchIds&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt; &lt;span class="c1"&gt;// null = whole-school user&lt;/span&gt;

    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$allowed&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nb"&gt;in_array&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="n"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nv"&gt;$asked&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$allowed&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ApiException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;ErrorCode&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="no"&gt;FORBIDDEN&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="s1"&gt;'You can only file records at a campus you are posted to.'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Whenever a column decides who may see a row, something must also decide who may set it.&lt;/strong&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Five rules we keep relearning
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;1. A campus is a view, not a permission.&lt;/strong&gt; If the system can't place a user on a campus (no staff row, no posting), do &lt;em&gt;not&lt;/em&gt; narrow their queries to nothing. That turns one missing row into a blank app with no error message. Permissions are the policies' job, not the scope's.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;2. Don't memoise per-request state in a long-lived object.&lt;/strong&gt; A route keeps the controller it built and can hand the same objects to the next request. A memo that isn't keyed to the request answers request two with request one's campus. We never register the scope as a &lt;code&gt;singleton&lt;/code&gt; or &lt;code&gt;scoped&lt;/code&gt; binding.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;3. Narrow by the root the screen's numbers come from.&lt;/strong&gt; We narrowed hostel allocations by the &lt;em&gt;student's&lt;/em&gt; campus, while the bed count came from the &lt;em&gt;building&lt;/em&gt;. The dashboard proudly showed &lt;strong&gt;108% bed occupancy&lt;/strong&gt;. A library loan narrows by the book, not the borrower.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;4. Check your unique indexes, not just your queries.&lt;/strong&gt; &lt;code&gt;payroll_runs.period&lt;/code&gt; was unique, so the second campus to run September's payroll was refused by the database. It is now unique on &lt;code&gt;(branch_id, period)&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;5. Never narrow the arithmetic.&lt;/strong&gt; A clash check for a bus driver, or a count of occupied beds in a room, must read across every campus. A narrowed count would happily double-book a driver or put two children in one bed.&lt;/p&gt;

&lt;h2&gt;
  
  
  Events carry their own campus
&lt;/h2&gt;

&lt;p&gt;One exception to "a child row reaches its campus through its parent" is events. Attendance, grades, fee invoices and payments record something that happened on a date. When a student transfers campus, last term's registers must stay with the campus that took them. So these four tables stamp the campus at write time. It looks like duplication, but it is two different facts: where the child is now, and where it happened.&lt;/p&gt;

&lt;h2&gt;
  
  
  The pattern behind all of it
&lt;/h2&gt;

&lt;p&gt;Each bug had the same shape: a boundary enforced on the obvious surface and missed on the aggregate one. Our dashboard stat cards came from a reports module, not from each module's own controller. So when we converted a module, its table narrowed while the numbers above it stayed school-wide. Now, whenever we add a boundary, we grep for every place that &lt;em&gt;counts&lt;/em&gt; the thing as well as every place that &lt;em&gt;lists&lt;/em&gt; it.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;We write practical guides for school owners in Pakistan, and you can try the school system in a &lt;a href="https://karobar.cloud" rel="noopener noreferrer"&gt;live demo&lt;/a&gt; with no sign-up. Questions about the multi-tenant setup are welcome in the comments.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>laravel</category>
      <category>php</category>
      <category>saas</category>
      <category>architecture</category>
    </item>
    <item>
      <title>Freelance developer? Here's the business insurance clients will actually ask you for</title>
      <dc:creator>Naveed Malik</dc:creator>
      <pubDate>Sat, 31 Oct 2026 11:17:35 +0000</pubDate>
      <link>https://dev.to/malkoo1/freelance-developer-heres-the-business-insurance-clients-will-actually-ask-you-for-3b8m</link>
      <guid>https://dev.to/malkoo1/freelance-developer-heres-the-business-insurance-clients-will-actually-ask-you-for-3b8m</guid>
      <description>&lt;p&gt;Sooner or later a client contract arrives with an "Insurance" clause: &lt;em&gt;Professional liability, $1,000,000 per claim. Certificate of insurance before kickoff. Name us as additional insured.&lt;/em&gt; If you just want to write code, it's easy to sign without knowing what any of that means.&lt;/p&gt;

&lt;p&gt;If you freelance or contract as a developer, you'll hit this sooner or later, usually with bigger clients, agencies and anything enterprise. Here's a plain-English map of what those clauses mean, which policies developers usually need, and what they typically cost. It's meant as a starting point, not the final word.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Disclosure: I run &lt;a href="https://insurancebytrade.com" rel="noopener noreferrer"&gt;InsuranceByTrade&lt;/a&gt;, a free, independent site that explains small-business insurance by trade. It sells nothing and isn't an insurance agency. I'm not a licensed insurance professional, so treat this as orientation, not advice. This post was drafted with AI assistance and checked by me.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  The short version
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Policy&lt;/th&gt;
&lt;th&gt;What it covers for a developer&lt;/th&gt;
&lt;th&gt;Median cost (Insureon 2026)&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Professional liability (tech E&amp;amp;O)&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Claims that your work caused a client a financial loss: a bug, a missed deadline, a feature that didn't do what was promised&lt;/td&gt;
&lt;td&gt;$88/month all businesses (about $1,056/year)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Cyber insurance&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Data breaches and cyber incidents: notification costs, recovery, related claims&lt;/td&gt;
&lt;td&gt;$129/month all businesses (about $1,548/year)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;General liability&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Bodily injury or property damage to other people, e.g. you knock over a client's monitor on site&lt;/td&gt;
&lt;td&gt;$30/month for technology businesses&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Business owner's policy (BOP)&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;General liability plus coverage for your own business property&lt;/td&gt;
&lt;td&gt;$46/month for technology businesses&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Insureon's 2026 medians come from 100,000 small-business customers, mostly businesses with 1–4 employees. Your price depends on revenue, the kind of work, the limits you choose, your deductible and your claims history.&lt;/p&gt;

&lt;h2&gt;
  
  
  Professional liability (E&amp;amp;O) is the one that matters
&lt;/h2&gt;

&lt;p&gt;For most developers, the realistic risk isn't someone tripping over a cable. It's a client saying your work cost them money. For example (illustrative):&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;An e-commerce checkout you built has a bug that silently drops orders over a weekend, and the client claims lost revenue.&lt;/li&gt;
&lt;li&gt;A migration script you wrote corrupts customer records, and the client pays to restore them.&lt;/li&gt;
&lt;li&gt;You miss a launch deadline written into the contract, and the client says it cost them a partnership.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Even if you did nothing wrong, &lt;strong&gt;defending&lt;/strong&gt; a claim costs money. Professional liability (often called &lt;em&gt;errors and omissions&lt;/em&gt;, or &lt;em&gt;tech E&amp;amp;O&lt;/em&gt; for software work) covers claims of negligence, mistakes or failing to deliver a professional service, including legal defense.&lt;/p&gt;

&lt;p&gt;General liability does &lt;strong&gt;not&lt;/strong&gt; cover professional mistakes. It's an easy thing to get wrong.&lt;/p&gt;

&lt;h2&gt;
  
  
  Decoding the contract clause
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;"$1,000,000 per claim / $2,000,000 aggregate"&lt;/strong&gt;: the most the policy pays for one claim, and the most it pays in total during the policy year. $1M per occurrence and $2M aggregate is the most common general liability limit.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;"Certificate of insurance (COI)"&lt;/strong&gt;: a one-page document from your insurer proving you have coverage. Clients, agencies and venues ask for it before you start. Your insurer issues it once you have a policy.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;"Additional insured"&lt;/strong&gt;: the client wants to be added to &lt;em&gt;your&lt;/em&gt; policy so it also protects them if they're pulled into a claim about your work. It's a common ask; your insurer adds it with an endorsement.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;"Claims-made" vs "occurrence"&lt;/strong&gt;: E&amp;amp;O policies are often &lt;em&gt;claims-made&lt;/em&gt;. They cover claims &lt;strong&gt;filed&lt;/strong&gt; while the policy is active. If you cancel the policy and a client sues next year about old work, you may have no cover unless you bought &lt;em&gt;tail coverage&lt;/em&gt;. Occurrence policies (typical for general liability) cover incidents that &lt;strong&gt;happened&lt;/strong&gt; during the policy period, whenever the claim is filed.&lt;/p&gt;

&lt;h2&gt;
  
  
  Do you actually need it?
&lt;/h2&gt;

&lt;p&gt;Usually no law requires a solo developer to carry business insurance. In practice the requirement comes from &lt;strong&gt;clients&lt;/strong&gt;: larger companies, agencies and government contracts often won't sign without a COI.&lt;/p&gt;

&lt;p&gt;A rough guide:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Solo, small clients, low-risk work&lt;/strong&gt;: often no requirement, but E&amp;amp;O is still worth pricing.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Agency or enterprise contracts&lt;/strong&gt;: expect a professional liability requirement, usually $1M.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;You handle client data, payments or health info&lt;/strong&gt;: add cyber insurance to the list.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;You hire employees&lt;/strong&gt;: most states require workers' compensation once you have employees. The thresholds vary a lot by state; &lt;a href="https://insurancebytrade.com/workers-comp-requirements-by-state" rel="noopener noreferrer"&gt;here's a state-by-state table&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Ways to keep the cost down
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Write a clear contract&lt;/strong&gt;: scope, acceptance criteria and a limitation-of-liability clause reduce both risk and premium.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Choose limits that match your contracts&lt;/strong&gt;, not the biggest number on the form.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Bundle&lt;/strong&gt; general liability and property into a BOP if you need both.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Pay annually&lt;/strong&gt; if the insurer discounts it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Keep your claims history clean&lt;/strong&gt;: version control, backups and written change requests are also good evidence if a dispute ever happens.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Further reading
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;a href="https://insurancebytrade.com/it-consultant-insurance" rel="noopener noreferrer"&gt;IT consultant insurance: tech E&amp;amp;O and cost&lt;/a&gt;: a deeper dive on E&amp;amp;O, claims-made retro dates and contract clauses&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://insurancebytrade.com/independent-contractor-insurance" rel="noopener noreferrer"&gt;Independent contractor insurance&lt;/a&gt;: if you work on a 1099&lt;/li&gt;
&lt;li&gt;&lt;a href="https://insurancebytrade.com/business-insurance-cost-calculator" rel="noopener noreferrer"&gt;Small business insurance cost calculator&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you've been through an insurance clause negotiation with a client, I'd love to hear how it went in the comments. What did they ask for, and what did you push back on?&lt;/p&gt;

</description>
      <category>freelance</category>
      <category>career</category>
      <category>webdev</category>
      <category>beginners</category>
    </item>
    <item>
      <title>How I built a 50-state paycheck calculator in Laravel (with no database)</title>
      <dc:creator>Naveed Malik</dc:creator>
      <pubDate>Thu, 22 Oct 2026 09:52:16 +0000</pubDate>
      <link>https://dev.to/malkoo1/how-i-built-a-50-state-paycheck-calculator-in-laravel-with-no-database-gfc</link>
      <guid>https://dev.to/malkoo1/how-i-built-a-50-state-paycheck-calculator-in-laravel-with-no-database-gfc</guid>
      <description>&lt;p&gt;US payroll taxes look simple until you try to code them. Federal brackets are the easy part. Then you meet 50 states, plus DC, that each do something slightly different. Alabama lets you deduct the federal tax you paid. Pennsylvania taxes your 401(k) contributions. Ohio adds a fixed dollar amount once you pass a threshold. Utah gives a credit that shrinks as your income rises.&lt;/p&gt;

&lt;p&gt;I wanted a free take-home pay calculator that handles all of that, shows its working, and loads fast. The result is &lt;a href="https://netpaymeter.com" rel="noopener noreferrer"&gt;NetPayMeter&lt;/a&gt;. This post covers how it's built: one tax engine, state rules as data, server-rendered results, and an embeddable widget.&lt;/p&gt;

&lt;h2&gt;
  
  
  The stack
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Laravel 12&lt;/strong&gt; on PHP 8.3&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;No database.&lt;/strong&gt; Every tax rule lives in PHP config files, and page copy lives in Markdown files.&lt;/li&gt;
&lt;li&gt;Plain JavaScript for the front end, with no framework and no build step.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;GitHub Actions&lt;/strong&gt; runs the tests, builds a release tarball, and deploys it to a small VPS over SSH.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Skipping the database was the best decision in the project. Tax data changes once a year, it needs code review, and it's read-only at runtime. Config files give me all three for free: the diff in a pull request &lt;em&gt;is&lt;/em&gt; the tax update.&lt;/p&gt;

&lt;h2&gt;
  
  
  One engine for everything
&lt;/h2&gt;

&lt;p&gt;Every calculator on the site goes through one class, &lt;code&gt;TaxEngine&lt;/code&gt;. That includes the paycheck, hourly, salary, overtime, W-4, 1099 and self-employment calculators. So do the worked examples printed in the page copy. If the engine is right, the whole site is right.&lt;/p&gt;

&lt;p&gt;At its heart is a progressive-bracket function. Brackets are stored as &lt;code&gt;[upper limit, rate]&lt;/code&gt; pairs, with &lt;code&gt;null&lt;/code&gt; meaning "no limit":&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight php"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;function&lt;/span&gt; &lt;span class="n"&gt;bracketTax&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;float&lt;/span&gt; &lt;span class="nv"&gt;$income&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;array&lt;/span&gt; &lt;span class="nv"&gt;$brackets&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="kt"&gt;array&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nv"&gt;$tax&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mf"&gt;0.0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nv"&gt;$lower&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mf"&gt;0.0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nv"&gt;$rows&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[];&lt;/span&gt;
    &lt;span class="nv"&gt;$marginal&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nv"&gt;$brackets&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;][&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$brackets&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nv"&gt;$upper&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$rate&lt;/span&gt;&lt;span class="p"&gt;])&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$income&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;=&lt;/span&gt; &lt;span class="nv"&gt;$lower&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="k"&gt;break&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="nv"&gt;$top&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nv"&gt;$upper&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="nv"&gt;$income&lt;/span&gt; &lt;span class="o"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;min&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$income&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$upper&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
        &lt;span class="nv"&gt;$amount&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nv"&gt;$top&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="nv"&gt;$lower&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="nv"&gt;$part&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nv"&gt;$amount&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="nv"&gt;$rate&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="nv"&gt;$tax&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="nv"&gt;$part&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="nv"&gt;$rows&lt;/span&gt;&lt;span class="p"&gt;[]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'from'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nv"&gt;$lower&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'to'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nv"&gt;$top&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'rate'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nv"&gt;$rate&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'amount'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nv"&gt;$amount&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'tax'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nv"&gt;$part&lt;/span&gt;&lt;span class="p"&gt;];&lt;/span&gt;
        &lt;span class="nv"&gt;$marginal&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nv"&gt;$rate&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$upper&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="k"&gt;break&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="nv"&gt;$lower&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nv"&gt;$upper&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'tax'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nv"&gt;$tax&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'marginal'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nv"&gt;$marginal&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'rows'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nv"&gt;$rows&lt;/span&gt;&lt;span class="p"&gt;];&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It returns the rows as well as the total, so the results page can show a "how your tax was calculated" table. A flat-tax state is just a single bracket: &lt;code&gt;[[null, .025]]&lt;/code&gt; is Arizona's 2.5%.&lt;/p&gt;

&lt;h2&gt;
  
  
  State rules as data, not code
&lt;/h2&gt;

&lt;p&gt;The tricky part is the state-by-state quirks. Writing 51 &lt;code&gt;if&lt;/code&gt; branches would have been unmaintainable. Instead, each state is an array in &lt;code&gt;config/states.php&lt;/code&gt;, and the engine understands a small set of optional keys:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Key&lt;/th&gt;
&lt;th&gt;What it handles&lt;/th&gt;
&lt;th&gt;Example&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;brackets&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Progressive or flat rates, per filing status&lt;/td&gt;
&lt;td&gt;Every state with an income tax&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;base =&amp;gt; 'federal_taxable'&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;State starts from federal taxable income&lt;/td&gt;
&lt;td&gt;Colorado, Iowa, Idaho&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;deducts_401k =&amp;gt; false&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;401(k) contributions are taxed&lt;/td&gt;
&lt;td&gt;Pennsylvania&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;std_phaseout&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Standard deduction shrinks as income rises&lt;/td&gt;
&lt;td&gt;Alabama, South Carolina, Wisconsin&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;fed_tax_deduct&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Federal income tax is deductible (with caps and phase-outs)&lt;/td&gt;
&lt;td&gt;Alabama, Oregon, Missouri&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;exemption_tiers&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Exemption depends on income&lt;/td&gt;
&lt;td&gt;Ohio&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;credit_phaseout&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Credit shrinks as income rises&lt;/td&gt;
&lt;td&gt;Utah&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;extras&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Employee payroll contributions with caps&lt;/td&gt;
&lt;td&gt;State disability or family-leave programs&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Here's Arizona, the simplest kind of state:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight php"&gt;&lt;code&gt;&lt;span class="s1"&gt;'arizona'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'name'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="s1"&gt;'Arizona'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'abbr'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="s1"&gt;'AZ'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'ready'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'type'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="s1"&gt;'flat'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="s1"&gt;'brackets'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'single'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;[[&lt;/span&gt;&lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mf"&gt;.025&lt;/span&gt;&lt;span class="p"&gt;]]],&lt;/span&gt;
    &lt;span class="s1"&gt;'std'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'single'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;16100&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'married'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;32200&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'hoh'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;24150&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt; &lt;span class="mf"&gt;...&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And here's how the engine handles a deduction that phases out. It needs only a few lines, and those lines work for every state that uses the key:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight php"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Standard deduction that shrinks as income rises (SC, WI): std − rate × (income − start).&lt;/span&gt;
&lt;span class="nv"&gt;$std&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;self&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="nf"&gt;forFiling&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$st&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'std'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$f&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;isset&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$st&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'std_phaseout'&lt;/span&gt;&lt;span class="p"&gt;]))&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nv"&gt;$over&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;max&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$base&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="k"&gt;self&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="nf"&gt;forFiling&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$st&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'std_phaseout'&lt;/span&gt;&lt;span class="p"&gt;][&lt;/span&gt;&lt;span class="s1"&gt;'start'&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt; &lt;span class="nv"&gt;$f&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
    &lt;span class="nv"&gt;$std&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;max&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;self&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="nf"&gt;forFiling&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$st&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'std_min'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$f&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="nv"&gt;$std&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="nv"&gt;$over&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="k"&gt;self&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="nf"&gt;forFiling&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$st&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'std_phaseout'&lt;/span&gt;&lt;span class="p"&gt;][&lt;/span&gt;&lt;span class="s1"&gt;'rate'&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt; &lt;span class="nv"&gt;$f&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Adding a new quirk means adding one optional key and a few lines to the engine. Adding a new state means adding data only. Each state also has a &lt;code&gt;ready&lt;/code&gt; flag: a page goes live, and into the sitemap, only after its numbers have been checked against that state's revenue department. Where the state publishes a withholding formula, the config links the official document (28 states so far).&lt;/p&gt;

&lt;p&gt;The current split is 26 progressive, 16 flat-rate, and 9 with no wage income tax that all share one &lt;code&gt;$none&lt;/code&gt; template. The no-tax states still matter: Washington has no income tax, but it does have two employee payroll contributions (Paid Family &amp;amp; Medical Leave and the WA Cares Fund), and the calculator includes both.&lt;/p&gt;

&lt;h2&gt;
  
  
  Tests are the published examples
&lt;/h2&gt;

&lt;p&gt;The page copy includes worked examples ("$60,000 a year, paid biweekly, single filer..."). Those exact numbers are also the test suite:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight php"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;function&lt;/span&gt; &lt;span class="n"&gt;test_paycheck_examples&lt;/span&gt;&lt;span class="p"&gt;():&lt;/span&gt; &lt;span class="kt"&gt;void&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nv"&gt;$this&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;assertSame&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mf"&gt;1938.08&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$this&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;net&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;&lt;span class="s1"&gt;'amount'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;60000&lt;/span&gt;&lt;span class="p"&gt;]));&lt;/span&gt;
    &lt;span class="nv"&gt;$this&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;assertSame&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mf"&gt;1836.54&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$this&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;net&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;&lt;span class="s1"&gt;'amount'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;60000&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'k401'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;5&lt;/span&gt;&lt;span class="p"&gt;]));&lt;/span&gt;
    &lt;span class="nv"&gt;$this&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;assertSame&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mf"&gt;845.42&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$this&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;net&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;&lt;span class="s1"&gt;'pay_type'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="s1"&gt;'hourly'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'amount'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;25&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'frequency'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="s1"&gt;'weekly'&lt;/span&gt;&lt;span class="p"&gt;]));&lt;/span&gt;
    &lt;span class="c1"&gt;// ...&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;When next year's brackets land, the tests fail in exactly the places where the page copy also needs updating. It's a cheap way to keep the text and the maths in sync.&lt;/p&gt;

&lt;h2&gt;
  
  
  Results are server-rendered HTML fragments
&lt;/h2&gt;

&lt;p&gt;There's no JSON API and no client-side tax logic. The form sends a &lt;code&gt;GET&lt;/code&gt; request to &lt;code&gt;/calc/{type}&lt;/code&gt;, and Laravel returns a rendered Blade partial:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight php"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;function&lt;/span&gt; &lt;span class="n"&gt;calculate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;Request&lt;/span&gt; &lt;span class="nv"&gt;$request&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="nv"&gt;$type&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nf"&gt;abort_unless&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;in_array&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$type&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'paycheck'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'federal'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'overtime'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="cm"&gt;/* ... */&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="mi"&gt;404&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="nv"&gt;$data&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nv"&gt;$this&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;calcData&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$request&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$type&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[]);&lt;/span&gt;

    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;response&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nf"&gt;view&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"calculators.results.&lt;/span&gt;&lt;span class="nv"&gt;$type&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$data&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="nb"&gt;header&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'X-Robots-Tag'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'noindex'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A few lines of JavaScript debounce the inputs, call &lt;code&gt;fetch()&lt;/code&gt;, and swap the HTML into the page. This has some nice side effects:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;One source of truth.&lt;/strong&gt; The tax maths exists only in PHP, so it can't drift from a JavaScript copy.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;It works without JavaScript.&lt;/strong&gt; The form is a normal &lt;code&gt;GET&lt;/code&gt; form, so the full page renders server-side too.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Shareable results.&lt;/strong&gt; Every calculation is a URL with query parameters.&lt;/li&gt;
&lt;li&gt;The fragments send &lt;code&gt;X-Robots-Tag: noindex&lt;/code&gt;, so search engines don't index thousands of near-duplicate result fragments.&lt;/li&gt;
&lt;li&gt;The endpoint is rate-limited with Laravel's &lt;code&gt;throttle:120,1&lt;/code&gt; middleware.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;All user input passes through one normaliser that clamps every number to a sane range (hours 0 to 100, salary up to $10M, and so on), so odd query strings can't produce odd results.&lt;/p&gt;

&lt;h2&gt;
  
  
  The embeddable widget uses Shadow DOM
&lt;/h2&gt;

&lt;p&gt;I wanted other sites, such as blogs, relocation guides and HR pages, to be able to embed the calculator with two lines:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight html"&gt;&lt;code&gt;&lt;span class="nt"&gt;&amp;lt;div&lt;/span&gt; &lt;span class="na"&gt;data-netpaymeter=&lt;/span&gt;&lt;span class="s"&gt;"paycheck"&lt;/span&gt;&lt;span class="nt"&gt;&amp;gt;&amp;lt;/div&amp;gt;&lt;/span&gt;
&lt;span class="nt"&gt;&amp;lt;script &lt;/span&gt;&lt;span class="na"&gt;src=&lt;/span&gt;&lt;span class="s"&gt;"https://netpaymeter.com/widget.js"&lt;/span&gt; &lt;span class="na"&gt;async&lt;/span&gt;&lt;span class="nt"&gt;&amp;gt;&amp;lt;/script&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;widget.js&lt;/code&gt; finds each &lt;code&gt;data-netpaymeter&lt;/code&gt; element and attaches a &lt;strong&gt;shadow root&lt;/strong&gt; where the browser supports it. It then fetches &lt;code&gt;/widget/{key}&lt;/code&gt;, which returns the same calculator form with the site's CSS inlined. Before inlining, the server rewrites &lt;code&gt;:root&lt;/code&gt; to &lt;code&gt;:host&lt;/code&gt; so the CSS variables apply inside the shadow tree:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight php"&gt;&lt;code&gt;&lt;span class="nb"&gt;preg_replace&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;&lt;span class="s1"&gt;'/:root\b/'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'/(^|\})\s*body\s*\{/'&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;':host'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'$1 .npw {'&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt; &lt;span class="nv"&gt;$css&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The Shadow DOM means the host page's CSS can't break the calculator, and the calculator's CSS can't leak out and break the host page. CORS is enabled only for the &lt;code&gt;calc/*&lt;/code&gt; and &lt;code&gt;widget/*&lt;/code&gt; paths, and only for &lt;code&gt;GET&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;One lesson learned: nginx caches &lt;code&gt;.js&lt;/code&gt; files for a year, so &lt;code&gt;widget.js&lt;/code&gt; has to stay backward compatible forever. There's a comment at the top of the file saying exactly that.&lt;/p&gt;

&lt;h2&gt;
  
  
  Deploys
&lt;/h2&gt;

&lt;p&gt;A push to &lt;code&gt;main&lt;/code&gt; runs PHPUnit, then builds a release tarball on GitHub's runners rather than on the server. It uploads the tarball over SSH (retrying if the connection drops), switches a symlink, and runs a public health check against &lt;code&gt;/&lt;/code&gt;, &lt;code&gt;/sitemap.xml&lt;/code&gt; and &lt;code&gt;/robots.txt&lt;/code&gt;. A manual workflow input rolls back to the previous release.&lt;/p&gt;

&lt;p&gt;The last step pings &lt;strong&gt;IndexNow&lt;/strong&gt; with every URL in the sitemap, so Bing and other IndexNow search engines learn about changes straight away. It's marked &lt;code&gt;continue-on-error&lt;/code&gt;, so a failed ping never fails a deploy.&lt;/p&gt;

&lt;h2&gt;
  
  
  What I'd tell someone building something similar
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Model the weird cases as data.&lt;/strong&gt; Every state quirk became an optional config key, so the engine stayed small.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Make your published examples your tests.&lt;/strong&gt; The copy and the maths can't silently drift apart.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Server-render the hard logic.&lt;/strong&gt; One implementation, testable in PHP, and the page works without JavaScript.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use Shadow DOM for embeds.&lt;/strong&gt; Style isolation in both directions is worth it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Link your sources.&lt;/strong&gt; Payroll tax is easy to get slightly wrong. Linking the official withholding documents keeps you honest and lets users check your work.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;You can try it at &lt;a href="https://netpaymeter.com" rel="noopener noreferrer"&gt;netpaymeter.com&lt;/a&gt; and see the embed options at &lt;a href="https://netpaymeter.com/embed" rel="noopener noreferrer"&gt;netpaymeter.com/embed&lt;/a&gt;. If you spot a state rule I've modelled wrong, I'd genuinely like to hear about it in the comments.&lt;/p&gt;

</description>
      <category>laravel</category>
      <category>php</category>
      <category>webdev</category>
      <category>showdev</category>
    </item>
  </channel>
</rss>
